| Command group | Flag affected | Reversible | Execute on client | Platform(s) |
|---|---|---|---|---|
| External commands | YES | NO | NO | All |
SMTPSend (server,from,to,subj,body{Char|Bin|MIME-List}[,cc,bcc,name,stsproc,pri,xtrahdrs,user,pass,secure {Default zero insecure;1 secure;2 use STARTTLS},verify {Default kTrue}]) Returns status
Note: The flag is set according to whether Omnis was able to make a call to this external command.
This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.
SMTPSend sends an Internet e-mail message via an SMTP server. It returns a Status value less than zero if an error occurs. Possible error codes are listed in the Web Command Error Codes Appendix.
Server is an Omnis Character field containing the IP address or hostname of an SMTP server that will accept e-mail requests from the client running Omnis, for example, smtp.server.com or 255.255.255.254. If the server is not using the default SMTP port (25 for non-secure connections, or 465 for secure connections), you can optionally append the port number on which the server is listening, using the syntax server:port, for example smtp.server.com:1234.
In addition, you can specify the argument of the HELO or EHLO command that will be sent to the server, via the Server parameter - pass the HELO/EHLO argument as a second string, separated from the server address or hostname by a comma, for example smtp.server.com:1234,www.mydomain.com. The argument of HELO or EHLO is typically the domain name of the sender.
From is an Omnis Character field containing the RFC 822 Internet e-mail address that will be placed in the header to identify the sender. Recipients can reply to this address, for example, webmaster@omnis.net.
To is either an Omnis Character field or an Omnis list field. If the field is character, it contains the RFC 822 Internet e-mail address to which the e-mail will be sent, for example, webmaster@omnis.net. If the field is a list, it has a single character column, which contains one RFC 822 Internet e-mail address per row.
Subject is an Omnis character field containing the subject of the e-mail message.
Body is
either an Omnis Character or Binary field containing the body of the e-mail message; the text appears as the actual e-mail message
or an Omnis list containing MIME body-parts. See the MailSplit command for a definition of the list. Note that you do not need to fill in the character set, content transfer encoding and content disposition columns. SMTPSend will automatically use the ISO-8859-1 character set for text, the 7bit encoding for message content, quoted-printable encoding for text content, and base64 encoding for all other content types. Also, SMTPSend assigns content disposition "attachment" to body parts with a file name. If you wish to override the default behavior for these three columns, you can.
CC specifies the carbon-copy recipients for the message. You pass this parameter in the same way as the To parameter.
BCC specifies the blind carbon-copy recipients for the message. You pass this parameter in the same way as the To parameter.
Name is an Omnis Character field containing a personal name that will appear in the header to identify the user by a more descriptive name than just the e-mail address, for example, Omnis Webmaster
StsProc is an optional parameter containing the name of an Omnis method that SMTPSend calls with status messages as submission of the message to the SMTP server proceeds. The method can display a status message to the user. SMTPSend calls the method with no parameters, and the status information in the variable #S1.
Pri is on Omnis Short Integer field that sets the priority of the e-mail. It accepts a single value in the range of 1 through 5, a 1 (one) indicating the highest priority.
XtraHdrs is an optional parameter which enables you to specify some additional SMTP headers to be sent with the message. . It is a 2 column list. Column 1 is the header name excluding the colon, and column 2 is the header value. For example, you could place 'Disposition-Notification-To' in column 1, and an email address in column 2, to send a 'Disposition-Notification-To' header. Note that SMTPSend does not validate the header, or attempt to filter out illegal duplicates.
User and Pass are required if SMTPSend is to use SMTP authentication when connecting to the server. If you omit the User parameter (or pass a zero length string) then the command does not attempt to use authentication when connecting to the server; otherwise, the command will use authentication when connecting to the server, where User is the user name and Pass is the password. Note that whereas SMTP supports many different forms of authentication, SMTPSend only supports the commonly used CRAM-MD5, LOGIN and PLAIN methods of authentication; if the server supports CRAM-MD5,then SMTPSend will use CRAM-MD5 if more than one of these three methods is available, as this is the most secure method of the three it supports.
Secure is an optional Boolean parameter which indicates if a secure connection is required to the server. Pass kTrue for a secure connection, in which case the built-in security technology will be used, so on Windows ‘Secure Channel’ (Schannel) is used, on macOS ‘Secure Transport’ is used, and on Linux OpenSSL is used.
SMTPSend also supports an alternative secure option, if you pass secure with the value 2, the connection is initially not secure, but after the initial exchange with the server, SMTPSend issues a STARTTLS SMTP command to make the connection secure if the server supports it (see RFC 3207 for details). Authentication occurs after a successful STARTTLS command.
Verify is an optional Boolean parameter which is only significant when Secure is not kFalse. When Verify is kTrue, the command instructs the installed SSL library to verify the server's identity using its certificate; if the verification fails, then the connection will not be established. You can pass Verify as kFalse, to turn off this verification; in this case, the connection will still be encrypted, but there is a chance the server is an impostor. In order to perform the verification, the installed SSL library uses the Certificate Authority Certificates in the cacerts sub-folder of the secure folder in the Omnis folder. If you use your own Certificate Authority to self-sign certificates, you can place its certificate in the cacerts folder, and the installed SSL library will use it after you restart Omnis.
Header Values Containing International Characters
SMTPSend supports RFC 2047, and uses it to encode international characters in header values, using UTF-8 as the character encoding.
# Send email via the smtp server iOutServer from the email address iOutFrom to the email addresses in pToAddressList
If pEnclosureList.$linecount>0
# if the new e-mail contains enclosures, compose and send as multipart MIME content
Do pEnclosureList.$redefine(lFileName,lFilePath)
Do lMimeList.$define(lLevel,lContentType,lContentSubType,lFileName,
lCharData,lBinData,lCharSet,lEncoding)
Do lMimeList.$add(0,'multipart','mixed')
Do lMimeList.$add(1,'text','plain',,pBody,,,)
For lLineInList from 1 to pEnclosureList.$linecount step 1
Do pEnclosureList.$line.$assign(lLineInList)
Do pEnclosureList.$loadcols()
Do lFileOps.$openfile(lFilePath)
Do lFileOps.$readfile(lFileBinData)
Do lFileOps.$closefile()
Do lMimeList.$add(1,'application','octet-stream',lFileName,,lFileBinData,,)
End For
SMTPSend (iOutServer,iOutFrom,pToAddresslist,pSubject,lMimeList,
pCCAddresslist,pBCCAddresslist,iOutFromName,pStatusCall,pPriority)
Returns lStatus
Else
# send message with no enclosures
SMTPSend (iOutServer,iOutFrom,pToAddresslist,pSubject,pBody,
pCCAddresslist,pBCCAddresslist,iOutFromName,pStatusCall,pPriority)
Returns lStatus
End If