%Net.SMTP

class %Net.SMTP extends %Library.RegisteredObject

For information on using this class, see Sending and Receiving Email.

Send a SMTP mail message

The Charset property of each %Net.MailMessagePart determines the charset for text MIME parts. The charset property is ignored unless ContentType=text/... Charset sets the Character Set for the content-type header. IMPORTANT: Charset must be set before any data is written to the TextData stream associated with this %Net.MailMessagePart. The Charset may also be initialized when the message is created by ##Class(%Net.MailMessagePart).%New(charset) or ##Class(%Net.MailMessage).%New(charset). For Unicode locale, the default Charset for ##Class(%Net.SMTP).%New() is utf-8.

  #include %occOptions
  #include %occStatus
  
  testmailsend3 ;
  ;  Replace information marked with [[ ]]
  
  new attached,err,m,nestedm,s,status
  set s=##class(%Net.SMTP).%New()
  set s.smtpserver=[["SMTP server name"]]
  set s.timezone=[["-0400"]]  may remove this line to get Universal Time
  set m=##class(%Net.MailMessage).%New()
  set m.From=[["test@company.com"]]
  // Either address with name or just email address supported.
  do m.To.Insert([["receiver@another.com"]])
  do m.To.Insert([["Joe Smith <jsmith@another.com>"]])
  write !,"s.port="_s.port
  write !,"s.localhost="_s.localhost
  set m.Subject="Sent by InterSystems IRIS mail"
  set m.Charset="iso-8859-1"
  set status=m.TextData.Write("This is the main body.")
  if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
  set status=m.TextData.Write($char(13,10))
  if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
  set status=m.TextData.Write("This is the second line.")
  if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
  set status=m.TextData.Write($char(13,10))
  if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
  set status=m.AttachFile("c:\winnt","notepad.exe")
  if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
  // Attach a text file with charset=iso-8859-1
  set status=m.AttachFile("d:\temp","test.txt",0,"iso-8859-1")
  if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
  set nestedm=m.AttachNewMessage()
  // Attach a binary file
  set status=nestedm.AttachFile("c:\irissys\bin","test.bin")
  if $$$ISERR(status) do $system.OBJ.DisplayError(status) quit
  write !,"m.Parts.Count()="_m.Parts.Count()
  write !,"m.Parts.GetAt(3).Parts.GetAt(1).FileName="_m.Parts.GetAt(3).Parts.GetAt(1).FileName
  write !,"m.Parts.GetAt(3).Parts.Count()="_m.Parts.GetAt(3).Parts.Count()
  set status=s.Send(m)
  if $$$ISERR(status) do $system.OBJ.DisplayError(status)
  quit

Property Inventory

AllowHeaderEncoding
AuthFrom
ContinueAfterBadSend
Debug
Error
FailedSend
IPVersion
IgnoreFailedAuth
SSLCheckServerIdentity
SSLConfiguration
ShowBcc
Timeouts
UseSTARTTLS
authenticator
bufcount
localhost
port
smtpserver
timezone

Parameters

parameter Base64Seq = ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/;

parameter PrintableAscii = !""#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~;

Properties

property AllowHeaderEncoding as %Boolean [ InitialExpression = 1 ];

If true, the Send() method will encode non-ASCII header text according to the rules specified by RFC 2047. This is the default. Some mail readers do not accept the encoding specified by RFC 2047 and thus we allow disabling this encoding by setting AllowHeaderEncoding=false.

Property methods: AllowHeaderEncodingDisplayToLogical(), AllowHeaderEncodingGet(), AllowHeaderEncodingIsValid(), AllowHeaderEncodingLogicalToDisplay(), AllowHeaderEncodingNormalize(), AllowHeaderEncodingSet()

property AuthFrom as %String (MAXLEN = 255, TRUNCATE = 1);

AuthFrom specifies the address to be used for the AUTH parameter of the MAIL FROM SMTP command for SMTP authenticated session. If specified, this property will be the argument of the AUTH= extension to the MAIL FROM command. This property may be specified as "<>" to indicate that the original submitter of the messge is not known.

Property methods: AuthFromDisplayToLogical(), AuthFromGet(), AuthFromIsValid(), AuthFromLogicalToDisplay(), AuthFromLogicalToOdbc(), AuthFromNormalize(), AuthFromSet()

property ContinueAfterBadSend as %Boolean [ InitialExpression = 0 ];

If true, sending the email will continue if a send fails and failed email addresses will be added to the FailedSend list.

Property methods: ContinueAfterBadSendDisplayToLogical(), ContinueAfterBadSendGet(), ContinueAfterBadSendIsValid(), ContinueAfterBadSendLogicalToDisplay(), ContinueAfterBadSendNormalize(), ContinueAfterBadSendSet()

property Debug as %Integer [ InitialExpression = 0 ];

Property methods: DebugDisplayToLogical(), DebugGet(), DebugIsValid(), DebugLogicalToDisplay(), DebugNormalize(), DebugSet()

property Error as %String (MAXLEN = 255, TRUNCATE = 1);

If Send is called and returns an error status, the error message is in the Error property.

Property methods: ErrorDisplayToLogical(), ErrorGet(), ErrorIsValid(), ErrorLogicalToDisplay(), ErrorLogicalToOdbc(), ErrorNormalize(), ErrorSet()

property FailedSend as list of %String (MAXLEN = 8000, TRUNCATE = 1);

A list of email addresses for which the Send failed. If the Send for any address is successful, then a %Status of $$$OK is returned by Send and this list contains any failed addresses. If Send is not successful for any email address, then an %Status of $$$SMTPNoSend and all address on this list. Use (sender.FailedSend.Count()=0) to test if all sends succeeded.

Property methods: FailedSendBuildValueArray(), FailedSendCollectionToDisplay(), FailedSendCollectionToOdbc(), FailedSendDisplayToCollection(), FailedSendDisplayToLogical(), FailedSendGet(), FailedSendGetObject(), FailedSendGetObjectId(), FailedSendGetSwizzled(), FailedSendIsValid(), FailedSendLogicalToDisplay(), FailedSendLogicalToOdbc(), FailedSendNormalize(), FailedSendOdbcToCollection(), FailedSendSet(), FailedSendSetObject(), FailedSendSetObjectId()

property IPVersion as %Integer [ InitialExpression = 0 ];

IPVersion specifies the versin of IP address to be used to connect SMTP server. The valid values are:
0 - Try to connect with IPV4 first if failed then try it again with IPV6.
4 - Connect to SMTP server with IPV4 address.
6 - Connect to SMTP server with IPV6 address.
All other values are treated as 0.

Property methods: IPVersionDisplayToLogical(), IPVersionGet(), IPVersionIsValid(), IPVersionLogicalToDisplay(), IPVersionNormalize(), IPVersionSet()

property IgnoreFailedAuth as %Boolean [ InitialExpression = 0 ];

If false (as is the default), Send() will fail if there is an authenticator present but authentication with the server fails. If true, Send() will ignore a failure to authenticate and proceed with sending without authentication. If no authenticator is present, authentication is never attempted and so this property is ignored.

Property methods: IgnoreFailedAuthDisplayToLogical(), IgnoreFailedAuthGet(), IgnoreFailedAuthIsValid(), IgnoreFailedAuthLogicalToDisplay(), IgnoreFailedAuthNormalize(), IgnoreFailedAuthSet()

property SSLCheckServerIdentity as %Boolean [ InitialExpression = 1 ];

When making an SSL connection check the server identity in the server certificate matches the name of the system we are connecting to. This defaults to being on and matches based on the rules layed out in section 3.1 of RFC 2818.

Property methods: SSLCheckServerIdentityDisplayToLogical(), SSLCheckServerIdentityGet(), SSLCheckServerIdentityIsValid(), SSLCheckServerIdentityLogicalToDisplay(), SSLCheckServerIdentityNormalize(), SSLCheckServerIdentitySet()

property SSLConfiguration as %String;

The name of the activated TLS/SSL configuration to use for smpts requests.

Property methods: SSLConfigurationDisplayToLogical(), SSLConfigurationGet(), SSLConfigurationIsValid(), SSLConfigurationLogicalToDisplay(), SSLConfigurationLogicalToOdbc(), SSLConfigurationNormalize(), SSLConfigurationSet()

property ShowBcc as %Boolean;

If ShowBcc = true (1), then Bcc headers will be written to the email message. The Bcc headers will usually be filtered out by the SMTP server.

Property methods: ShowBccDisplayToLogical(), ShowBccGet(), ShowBccIsValid(), ShowBccLogicalToDisplay(), ShowBccNormalize(), ShowBccSet()

property Timeouts [ MultiDimensional ];

A mapping of SMTP commands to the timeouts (in seconds) used for them.
By default, timeouts based on RFC 1123 guidelines are used.

The keys "EHLO", "HELO", "MAIL, "RCPT", "DATA", "AUTH", "STARTTLS", "QUIT", and "RSET" are supported to specify the timeout when waiting for a server response to the corresponding commands. The following special values are also supported:

"_initial" - Set the timeout used when waiting for the initial greeting from the server
"_data termination" - Set the timeout used when waiting for the server response to the termination of the message data

If a negative timeout value is specified, it will be ignored and the default will be used instead.
Below is an example of how to use this property to configure the timeouts.

  set s=##class(%Net.SMTP).%New()
  set s.Timeouts("EHLO") = 100 ; use a 100s timeout when waiting for a response to the EHLO command
  set s.Timeouts("MAIL") = 200 ; use a 200s timeout when waiting for a response to the MAIL command

Property methods: TimeoutsDisplayToLogical(), TimeoutsGet(), TimeoutsIsValid(), TimeoutsLogicalToDisplay(), TimeoutsLogicalToOdbc(), TimeoutsNormalize(), TimeoutsSet()

property UseSTARTTLS as %Boolean;

If true then the STARTTLS extension to SMTP (RFC 3207) should be used to authenticate to the SMTP server on the normal SMTP port. The SSLConfiguration must be specified.

Property methods: UseSTARTTLSDisplayToLogical(), UseSTARTTLSGet(), UseSTARTTLSIsValid(), UseSTARTTLSLogicalToDisplay(), UseSTARTTLSNormalize(), UseSTARTTLSSet()

property authenticator as %Net.Authenticator;

To do SMTP authentication with the SMTP server (as defined by RFC 2554), instantiate a %Net.Authenticator object, set UserName and Password properties of the authenticator and assign it to this property. An example of the use of authenticator follows.

  #include %occOptions
  #include %occStatus
  
  authtestmailsend ;
  ;  Replace information marked with [[ ]]
  
  new auth,m,s,status
  set s=##class(%Net.SMTP).%New()
  set auth=##class(%Net.Authenticator).%New() ; use default authentication list
  set auth.UserName=[["myUser"]]
  set auth.Password=[["myPassword"]]
  set s.authenticator=auth
  set s.smtpserver=[["SMTP server name"]]
  set s.timezone=[["-0400"]]  may remove this line to get Universal Time
  set m=##class(%Net.MailMessage).%New()
  set m.From=[["test@company.com"]]
  do m.To.Insert([["receiver@another.com"]])
  do m.To.Insert([["Joe Smith <jsmith@another.com>"]])
  set m.Subject="Sent by InterSystems IRIS mail"
  set m.Charset="iso-8859-1"
  do m.TextData.Write("This message has been sent using an SMTP server with Authentication.")
  set status=s.Send(m)
  if $$$ISERR(status) do $system.OBJ.DisplayError(status)
  quit

Property methods: authenticatorGet(), authenticatorGetSwizzled(), authenticatorIsValid(), authenticatorNewObject(), authenticatorSet()

property bufcount as %Integer [ InitialExpression = 1 ];

Property methods: bufcountDisplayToLogical(), bufcountGet(), bufcountIsValid(), bufcountLogicalToDisplay(), bufcountNormalize(), bufcountSet()

property localhost as %String (TRUNCATE = 1) [ InitialExpression = $ZU(110) ];

The sending host, default is $ZU(110).

Property methods: localhostDisplayToLogical(), localhostGet(), localhostIsValid(), localhostLogicalToDisplay(), localhostLogicalToOdbc(), localhostNormalize(), localhostSet()

property port as %String (MAXLEN = 100, TRUNCATE = 1);

The port of the SMTP server, the default is 25 for plain text and 465 for SSL.

Property methods: portDisplayToLogical(), portIsValid(), portLogicalToDisplay(), portLogicalToOdbc(), portNormalize(), portSet()

property smtpserver as %String (MAXLEN = 100, TRUNCATE = 1);

the name of the SMTP server

Property methods: smtpserverDisplayToLogical(), smtpserverGet(), smtpserverIsValid(), smtpserverLogicalToDisplay(), smtpserverLogicalToOdbc(), smtpserverNormalize(), smtpserverSet()

property timezone as %String (MAXLEN = 100, TRUNCATE = 1);

timezone as specified by RFC822, for example "EST", "PDT", "-0400". If timezone is "LOCAL", then the local timezone expressed as "+nnnn" or "-nnnn" is used. If timezone is not set, then "UT" is used for the timezone and universal time is used in the message.

Property methods: timezoneDisplayToLogical(), timezoneGet(), timezoneIsValid(), timezoneLogicalToDisplay(), timezoneLogicalToOdbc(), timezoneNormalize(), timezoneSet()

Methods

method EncodeXtext(text As %String) as %String

xtext encoding is defined in RFC 1891 as:

"xtext" is formally defined as follows:
xtext = *( xchar / hexchar )
xchar = any ASCII CHAR between "!" (33) and "~" (126) inclusive, except for "+" and "=".
;"hexchar"s are intended to encode octets that cannot appear
;as ASCII characters within an esmtp-value. hexchar = ASCII "+" immediately followed by two upper case hexadecimal digits

Setup session with the SMTP server. We will use the EHLO command and SMTP authentication as supplied by the authenticator property where possible. If EHLO is not accepted or authentication fails, we will attempt to use the HELO command.

method Send(msg As %Net.MailMessage) as %Status

Used to send msg to SMTP server.

Returns a %Status to indicate success or failure.

The send() supports the following small subset of permissible message header fields. Set the corresponding MailMessage properties before invoking send.

Date - set from msg.Date; will be set to the current date and time if not specified
From - set from msg.From
Subject - set from msg.Subject
To - set from msg.To by converting to "," separated list
Cc - optionally set from msg.Cc by converting to "," separated list
Bcc - optionally set from msg.Bcc by converting to "," separated list
Sender - optionally set from msg.Sender
Reply-To - optionally set from msg.ReplyTo

The "MAIL FROM:" SMTP command uses the Sender field if specified, otherwise the From field.
The "RCPT TO:" SMTP command uses the To and Cc lists joined by commas.
simple e-mail address must be passed to MAIL and RCPT. Therefore if the address is of the form name <email>, the value passed to the SMTP command is just email.

method zone() as %String

Return timezone converted to RFC822 format