RTI_Email_Client function
Description
The RTI_EMAIL_CLIENT function provides a general interface for sending, receiving, and managing email messages. It can communicate with IMAP, POP3, and SMTP servers.
NOTE: Prior to OpenInsight 10.2.2, RTI_EMAIL_CLIENT used the AE.NET.MAIL dll. Starting with OpenInsight 10.2.2, RTI_EMAIL_CLIENT is using the MailKit dll. This change may introduce differences in behavior between pre-10.2.2 and post-10.2.2 systems. For those users experiencing problems with the post-10.2.2 RTI_EMAIL_CLIENT, it is possible to instruct RTI_EMAIL_CLIENT to use its pre-10.2.2 code. Specify the option name "version" in options field 1, and "1.0" or "old" in options field 2.
Syntax
stat = RTI_EMAIL_CLIENT(MSG, PARM1, PARM2, …)
Parameters
The first parameter to the RTI_EMAIL_CLIENT function is the message or action that is requested, and is required. The remaining parameters are optional parameters that control the behavior of the message. Use the RTI_EMAIL_EQUATES insert for the equated message names.
Parameter Details
| Message | Description | Parameters |
|---|---|---|
| EMAIL_ACTION_CONNECT$ | Connect to the IMAP, SMTP, or POP3 server. If successful, return a "handle" for the connection (used in subsequent calls). | PARM1: Connection Type - EMAIL_SERVER_TYPE_POP$, EMAIL_SERVER_TYPE_IMAP$, or EMAIL_SERVER_TYPE_SMTP$ PARM2: Server name or URL PARM3: Server port PARM4: Authentication user name PARM5: Authentication password PARM6: Boolean "Use SSL" flag PARM7-PARM10: Unused PARM11: Additional options (see below) |
| EMAIL_ACTION_DISCONNECT$ | Disconnect from the currently-connected mail server. If successful, returns null | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call |
| EMAIL_ACTION_ERRORS$ | Retrieve any previously generated errors, and clear out the errors buffer. Returns the error message(s) or null. | None |
| EMAIL_ACTION_SEND$ | Send the specified email message. Note that this is valid only for SMTP connections. Returns null if successful. | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call PARM2: Sender name. May be specified as email address only, or as display name : @FM : email address PARM3: Recipient name(s). Multiple addresses are @VM or semicolon delimited. May be specified as email address(es) only, or as display name(s) : @FM : email address(es) PARM4: Subject text PARM5: Email body. Leave null, and specify alternate content, to send HTML email instead of plain-text. PARM6: cc address(es). Multiple addresses are @VM or semicolon delimited. May be specified as email address(es) only, or as display name(s) : @FM : email address(es) PARM7: bcc address(es). Multiple addresses are @VM or semicolon delimited. May be specified as email address(es) only, or as display name(s) : @FM : email address(es) PARM8: Reply-to address. May be specified as email address only, or as display name : @FM : email address PARM9: Alternate content. Field 1 contains the alternate content, and field 2 specifies the mime type (defaults to text/html). PARM10: Attachment list of file(s). Multiple files are @VM delimited. PARM11: Additional options (see below) |
| EMAIL_ACTION_FOLDER$ | Specify or change the folder that is currently active. Note that this is valid only for IMAP connections. Returns the number of messages in the mailbox if successful. | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call PARM2: Folder name |
| EMAIL_ACTION_SEARCH$ | Select messages with match the specified search criteria. Note that this is valid only for IMAP connections. Returns a "handle" to the selected message list if successful. | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call PARM2: List of parameter names to search. Multiple parameter names can be @FM delimited. By default, multiple parameters are ANDed together. Prefix the parameter name with "+" or "OR " to indicate an "OR" search; prefix the parameter with "NOT " to exclude messages that match the parameter. The full list of available parameters can be found in the RTI_EMAIL_EQUATES insert. PARM3: Associated list of parameter values for searching. Each field of the parameter names corresponds to a field in the parameter values. Multiple parameter values (for example, starting and ending values) can be @VM delimited within the field. Date values should be passed as internal dates. PARM4: (output) Will be filled in with the constructed search string |
| EMAIL_ACTION_COUNT$ | Return a count of the number of messages selected. Note that this is valid only for IMAP or POP connections. Returns the count of selected messages. | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call PARM2: "Handle" from EMAIL_ACTION_SEARCH$ call, if any. If not specified, the total number of messages in the current mailbox is retrieved. |
| EMAIL_ACTION_DELETE$ | Deletes the selected messages. Note that this is valid only for IMAP or POP connections. Returns null if successful. | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call PARM2: Starting mail message number PARM3: Engine mail message number PARM4: "Handle" from EMAIL_ACTION_SEARCH$ call, if any. |
| EMAIL_ACTION_FLAG$ | Marks the specified message(s). Note that this is valid only for IMAP connections. Returns null if successful. | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call PARM2: Starting mail message number PARM3: Ending mail message number PARM4: "Handle" from EMAIL_ACTION_SEARCH$ call, if any PARM5: Value to mark. Options include None, Seen, Answered, Flagged, Deleted, and Draft. Multiple values may be specified, @VM delimited. Defaults to "Seen" if not specified. |
| EMAIL_ACTION_RECEIVE$ | Retrieve the specified message(s) from the mail server. Note that this if valid only for IMAP or POP connections. Returns the message(s) if successful. Multiple messages are @RM delimited. Examine the RTI_EMAIL_EQUATES insert to determine the layout of the retrieved message. The EMSG_BODY$ field will have any crlf, cr, lf, or system delimiters converted into @TM. Fields EMSG_TO$, EMSG_CC$, and EMSG_REPLYTO$ may contain multiple values, @VM delimited. EMSG_ATTACHMENTS$ will contain subvalues specifying the filename (in value EMSG_ATTACHMENT_FILENAME$), encoding (in value EMSG_ATTACHMENT_ENCODING$), and mime type (in value EMSG_ATTACHMENT_TYPE$) for each attachment. If the mimetype is text (anything of the format "text/xxx"), the content will be found in value EMSG_ATTACHMENT_BODY$ (with crlf and any system delimiters converted to @TM). | PARM1: "Handle" from EMAIL_ACTION_CONNECT$ call PARM2: Starting mail message number PARM3: Ending mail message number PARM4: "Handle" from EMAIL_ACTION_SEARCH$ call, if any PARM5: Boolean flag to retrieve ONLY the message header information, and not the body (nor the attachments) PARM6: Boolean flag to skip attachments PARM7: Boolean flag to mark the messages as read when retrieved (only valid for IMAP connections) |
Additional options (passed in during the EMAIL_ACTION_CONNECT$ or EMAIL_ACTION_SEND$ messages) are specified as either name/value pairs (names and values separated by "=", and multiple pairs separated by ";") or a dynamic array (field 1 are the option names, @VM delimited; field 2 are the associated option values). Supported options currently include:
| Option Name | Available With Message | Valid Values |
|---|---|---|
| timeout | EMAIL_ACTION_CONNECT$ | the desired connection timeout |
| version | EMAIL_ACTION_CONNECT$ | either "1.0" or "old" to use the pre-10.2.2 email DLL |
| tlsprotocol | EMAIL_ACTION_CONNECT$ | the version of TLS to use for the connection Choices include tls11,tls12,tls13,systemdefault,ssl3, or tls |
| oauth | EMAIL_ACTION_CONNECT$ | either "ms" or "google" to use microsoft or google OAUTH logins (OpenInsight 10.2.2+) |
| priority | EMAIL_ACTION_SEND$ | high, low, or normal |
| receipt | EMAIL_ACTION_SEND$ | the email address to which the read receipt should be sent |
Returns
The return value will vary depending on the message. See the specific message information, above, for additional details. However, if any errors are encountered, the return value will be the literal ERROR: followed by a field mark (@FM) and the error message(s).
Example
To retrieve all the unseen emails:
searchParamNames = "UNSEEN" searchParamVals = ""
To retrieve all the unseen emails from anyone whose name included bryan
searchParamNames = "UNSEEN":@FM:"FROM" searchParamVals = "":@FM:"bryan"
To retrieve all the unseen emails from anyone whose name included bryan received since yesterday
searchParamNames = "UNSEEN":@FM:"FROM":@FM:"SINCE" searchParamVals = "":@FM:"bryan":@FM:DATE()-1