Thanks for your feedback!
Need to tell us more? Click here or use the Feedback button.

Is this page helpful?

Contents

Overview
Authenticating
Sending Email
Other Properties of %Net.SMTP
See Also

Sending Email via SMTP

This page describes how to use %Net.SMTPOpens in a new tab to send MIME email messages.

Overview

If you have access to an SMTP server, you can send email messages, as follows:

Create an instance of %Net.SMTPOpens in a new tab and authenticate to the SMTP server.
Create the email message to send (as described in Creating Email Messages).
Send the message and check the status returned by the SMTP instance.

Authenticating to the SMTP Server

To authenticate to the SMTP server, do the following:

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. For example:
```
  Set server=##class(%Net.SMTP).%New()
  Set server.smtpserver="smtp.mysmtpserver.com"
  Set server.port=25
```
Specify the necessary credentials to authenticate to the server. 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.
For example:
```
  //Create object to carry authentication
  Set auth=##class(%Net.Authenticator).%New()
  Set auth.UserName="isctest@mysmtpserver.com"
  Set auth.Password="123pass" //should instead get password from a password store
  
  Set server.authenticator=auth
  Set server.AuthFrom=auth.UserName
```
For an alternative, see Enabling XOAUTH2 Authentication.
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.

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.

Sending Email

Once you have an instance of %Net.SMTPOpens in a new tab that is authenticated to an SMTP server, send email as follows:

Create the email message to send (as described in Creating Email Messages).
Call the Send() method of your SMTP instance. This method returns a status, which you should check.
If the returned status indicates an error, check the Error property, which contains the error message itself.
Check the FailedSend property, which contains a list of email addresses for which the send action failed.

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")

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.