Sending Email via SMTP

Overview

If you have access to an SMTP server, you can send email messages. The SMTP server must be running and you must have the needed permissions to use it. To send email, do the following:

1. Create an instance of %Net.SMTPOpens in a new tab and set its properties as needed, especially the following:

   • smtpserver is the name of the SMTP server you are using.

   • port is the port you are using on the SMTP server; the default is 25.

   • timezone specifies the time zone of the server, as specified by RFC 822Opens in a new tab, for example "EST" or "-0400" or "LOCAL". If this is not set, the message uses universal time.

   This object describes the SMTP server you will use.

2. If the SMTP server requires authentication, specify the necessary credentials. To do so:

   1. Create an instance of %Net.AuthenticatorOpens in a new tab.

   2. Set the UserName and Password properties of this object.

   3. Set the authenticator property of your %Net.SMTPOpens in a new tab instance equal to this object.

   4. If the message itself has an authorized sender, set the AuthFrom property of your %Net.SMTPOpens in a new tab instance.

   5. Set MechanismList, which specifies what authentication methods should be attempted. The mail server retains a list of accepted authentication mechanisms and the first mechanism in the MechanismList that is accepted will be used to connect to the server. Define a MechanismList that suits your application requirements and the server setting.

3. To use an SSL/TLS connection to the SMTP server:

   1. Set the SSLConfiguration property to the name of the activated SSL/TLS configuration to use.

      For information on creating and managing SSL/TLS configurations, see InterSystems TLS Guide. The SSL/TLS configuration includes an option called Configuration Name, which is the string to use in this setting.

   2. Set the UseSTARTTLS property to either 0 or 1.

      In most cases, use the value 0. Use the value 1 for the case in which the server interaction begins on a normal TCP socket and then switches to TLS on the same port as the normal socket. For details, see RFC 3207Opens in a new tab.

   3. Optionally set the SSLCheckServerIdentity property to 1. Do this if you want to verify the host server name in the certificate.

4. Create the email message to send (as described in Creating Single-part Email Messages and Creating Multipart Email Messages).

5. Call the Send() method of your SMTP instance. This method returns a status, which you should check.

6. If the returned status indicates an error, check the Error property, which contains the error message itself.

7. Check the FailedSend property, which contains a list of email addresses for which the send action failed.

The examples in the following sections use a couple of different free SMTP services that were available at the time this manual was written. No particular endorsement is implied by the selection of these services. Also note that the examples do not show the actual passwords.

Important:

%Net.SMTPOpens in a new tab writes the message body into a temporary file stream. By default, this file is written to the namespace directory and if the directory requires special write permissions, the file is not created and you get an empty message body.

You can define a new path for these temporary files and choose a path that does not restrict write access (for example, /tmp). To do so, set the global node %SYS("StreamLocation",namespace) where namespace is the namespace in which your code is running. For example:

 Set ^%SYS("StreamLocation","SAMPLES")="/tmp" 

If %SYS("StreamLocation",namespace) is null, then InterSystems IRIS uses the directory specified by %SYS("TempDir",namespace). If %SYS("TempDir",namespace) is not set, then InterSystems IRIS uses the directory specified by %SYS("TempDir")

Enabling XOAUTH2 Authentication

%Net.SMTPOpens in a new tab supports XOAUTH2 as an authentication method.

%Net.AuthenticatorOpens in a new tab has an access token property, which allows XOAUTH2 to be included in its mechanism list. If XOAUTH2 is included, %Net.AuthenticatorOpens in a new tab will use it as an authentication method; it will not do so otherwise. Users who do not wish to use XOAUTH2 with %Net.SMTPOpens in a new tab do not need to do anything.

Example 1: HotPOPAsSMTP() and SendSimpleMessage()

This example consists of two methods that you use together. The first creates an instance of %Net.SMTPOpens in a new tab that uses a test account that has already been set up on the HotPOP SMTP server:

ClassMethod HotPOPAsSMTP() As %Net.SMTP
{
  Set server=##class(%Net.SMTP).%New()
  Set server.smtpserver="smtp.hotpop.com"
  //HotPOP SMTP server uses the default port (25)
  Set server.port=25
  
  //Create object to carry authentication
  Set auth=##class(%Net.Authenticator).%New()
  Set auth.UserName="isctest@hotpop.com"
  Set auth.Password="123pass"
  
  Set server.authenticator=auth
  Set server.AuthFrom=auth.UserName
  Quit server
}

The next method sends a simple, unique message, using an SMTP server that you provide as the argument:

ClassMethod SendSimpleMessage(server As %Net.SMTP) As %List
{
  Set msg = ##class(%Net.MailMessage).%New()
  Set From=server.authenticator.UserName
  Set:From="" From="xxx@xxx.com"
  Set msg.From = From
  
  Do msg.To.Insert("xxx@xxx.com")
  //Do msg.Cc.Insert("yyy@yyy.com")
  //Do msg.Bcc.Insert("zzz@zzz.com")
  Set msg.Subject="Unique subject line here "_$H
  Set msg.IsBinary=0
  Set msg.IsHTML=0
  Do msg.TextData.Write("This is the message.")
  
  Set status=server.Send(msg)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status)
    Write server.Error
    Quit ""
  }
  Quit server.FailedSend
}

Example 2: YPOPsAsSMTP()

This example creates an instance of an instance of %Net.SMTPOpens in a new tab that uses YPOPs, which is client software that provides SMTP and POP3 access to a Yahoo email account. It uses a test account that has already been set up for this purpose:

ClassMethod YPOPsAsSMTP() As %Net.SMTP
{
  Set server=##class(%Net.SMTP).%New()
  //local host acts as the server
  Set server.smtpserver="127.0.0.1"
  //YPOPs uses default port, apparently
  Set server.port=25
  
  //Create object to carry authentication
  Set auth=##class(%Net.Authenticator).%New()
  //YPOPs works with a Yahoo email account
  Set auth.UserName="isc.test@yahoo.com"
  Set auth.Password="123pass"
  
  Set server.authenticator=auth
  Set server.AuthFrom=auth.UserName
  Quit server
}

You can use this with the SendSimpleMessage method shown in the previous example.

Example 3: SendMessage()

The following, more flexible method accepts both an SMTP server and an email message. The email message should already include a subject line (if required by the SMTP server), but does not have to include addresses. This method then sends the email message to a set of hardcoded test destinations:

ClassMethod SendMessage(server As %Net.SMTP, msg as %Net.MailMessage) as %Status
{
  Set From=server.authenticator.UserName
  //make sure From: user is same as used in authentication
  Set msg.From = From
  
  //finish addressing the message
  Do msg.To.Insert("xxx@xxx.com")
  //send the message to various test email addresses
  Do msg.To.Insert("isctest@hotpop.com")
  Do msg.To.Insert("isc_test@hotmail.com")
  Do msg.To.Insert("isctest001@gmail.com")
  Do msg.To.Insert("isc.test@yahoo.com")
  
  Set status=server.Send(msg)
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status)
    Write server.Error
    Quit $$$ERROR($$$GeneralError,"Failed to send message")
  }
  Quit $$$OK
}

This example is meant for use with the example methods SimpleMessage and MessageWithAttachment described in Adding Attachments to a Message.

Other Properties of %Net.SMTP

The %Net.SMTPOpens in a new tab class also has some other properties that you might need, depending on the SMTP server you are using:

• AllowHeaderEncoding specifies whether the Send() method encodes non-ASCII header text. The default is 1, which means that non-ASCII header text is encoded as specified by RFC 2047Opens in a new tab.

• ContinueAfterBadSend specifies whether to continue trying to send a message after detecting a failed email address. If ContinueAfterBadSend is 1, the system will add the failed email address to the list in the FailedSend property. The default is 0.

• ShowBcc specifies whether the Bcc headers are written to the email message. These will normally be filtered out by the SMTP server.

See Also

• Email Support in InterSystems IRIS

• Creating Email Messages