Creating Email Messages

Creating Single-Part Email Messages

To create a single-part email message, you use the %Net.MailMessageOpens in a new tab class. To create a mail message, do the following:

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

   Tip:

   You can specify a character set as the argument to %New(); if you do so, that sets the Charset property for the message. For information on how this affects the message, see Automatic Encoding and Character Translation.

2. Set the To, From, and Subject properties of your instance.

   • To — The list of email addresses to which this message will be sent. This property is a standard InterSystems IRIS list class; to work with it, you use the standard list methods: Insert(), GetAt(), RemoveAt(), Count(), and Clear().

   • From — The email address this message is sent from.

   • Subject — The subject of the message, if this is required by the SMTP server you are using.

3. Optionally set Date, Cc, Bcc, and other properties. For details, see Specifying Basic Email Headers.

4. If the message is not plain text, set the following properties to indicate the kind of message you are creating:

   • If this is an HTML message, set the IsHTML property to 1.

   • If this is a binary message, set the IsBinary property to 1.

5. To specify the character set of the message and its headers, set the Charset property as needed. (For details on how this affects the message, see Automatic Encoding and Character Translation.)

   Important:

   It is important to specify the character set before you add the contents of the message.

6. Add the contents of the message:

   • For plain text or HTML, use the TextData property, which is an instance of %FileCharacterStreamOpens in a new tab. You do not need to specify the TranslateTable property of this stream; that occurred automatically when you specified the character set of the mail message.

   • For binary data, use the BinaryData property, which is an instance of %FileBinaryStreamOpens in a new tab.

   Note that %FileCharacterStreamOpens in a new tab and %FileBinaryStreamOpens in a new tab are deprecated but are still supported for use in this way. It is not recommended to substitute different stream classes for this use case.

   Tip:

   When you specify the Filename property of the stream, be sure to use a directory to which the users will have write access.

   To work with these properties, use the standard stream methods: Write(), WriteLine(), Read(), ReadLine(), Rewind(), MoveToEnd(), and Clear(). You can also use the Size property of the stream, which gives you the size of the message contents.

Also see Creating Multipart Email Messages.

Example 1: CreateTextMessage()

The following method creates a simple message and specifies the addresses for it:

ClassMethod CreateTextMessage() As %Net.MailMessage
{
    Set msg = ##class(%Net.MailMessage).%New()
    set msg.From = "test@test.com"
    Do msg.To.Insert("xxx@xxx.com")
    Do msg.Cc.Insert("yyy@yyy.com")
    Do msg.Bcc.Insert("zzz@zzz.com")
    Set msg.Subject="subject line here"
    Set msg.IsBinary=0
    Set msg.IsHTML=0
    Do msg.TextData.Write("This is the message.")
    
    Quit msg
}

Example 2: SimpleMessage()

You may instead prefer to specify the addresses when you actually send the message (see Example 3: SendMessage() in Using an SMTP Server to Send Email). The following variation of the preceding example generates a text message with no addresses:

ClassMethod SimpleMessage() As %Net.MailMessage
{
  Set msg = ##class(%Net.MailMessage).%New()
  Set msg.Subject="Simple message "_$h
  Set msg.IsBinary=0
  Set msg.IsHTML=0
  Do msg.TextData.Write("This is the message.")
  Quit msg
}

Creating Multipart Email Messages

To create a multipart email message:

1. Create an instance of %Net.MailMessageOpens in a new tab and set its To, From, and Subject properties. Optionally set other properties to specify other message headers.

2. Set the IsMultiPart property to 1.

3. Set the MultiPartType property to one of the following: "related", "alternative", or "mixed". This affects the Content-Type header of the entire message.

4. For each part that the message should contain, create an instance of %Net.MailMessagePartOpens in a new tab and specify its properties as described in Creating Single-part Email Messages — starting with step 4.

5. For the parent email message, set the Parts property, which is an array. Insert each child message part into this array.

When you send the message, the %Net.SMTPOpens in a new tab class automatically sets the Content-Type header for the message as appropriate (given the value of the MultiPartType property).

Specifying Email Message Headers

As noted previously, both the message itself and each part of a message has a set of headers.

The %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab classes provide properties that give you easy access to the most commonly used headers, but you can add any header you need. This section provides information on all the headers as well as how to create custom headers.

The headers of a given message part are in the character set specified by the Charset property of that part.

Custom Headers

With both %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab, you can set or get custom headers by accessing the Headers property, which is an array with the following structure:

Array Key	Array Value
Name of the header, such as "Priority"	Value of the header

You use this property to contain additional headers such as X-Priority and others. For example:

 do msg.Headers.SetAt(1,"X-Priority")
 do msg.Headers.SetAt("High","X-MSMail-Priority")
 do msg.Headers.SetAt("High","Importance")

Different email servers and clients recognize different headers, so it can be useful to set multiple similar headers to be sure that the server or client receives a message with a header it can recognize.

Adding Attachments to a Message

You can add attachments to an email message or message part (specifically, to an instance of %Net.MailMessagePartOpens in a new tab or %Net.MailMessageOpens in a new tab). To do so, use the following methods:

Each of these methods adds the attachment to the Parts array of the original message (or message part), and automatically sets the IsMultiPart property to 1.

AttachFile()

method AttachFile(Dir As %String, 
                  File As %String, 
                  isBinary As %Boolean = 1, 
                  charset As %String = "", 
                  ByRef count As %Integer) as %Status {}

Attaches the given file to the email message. By default the file is sent as a binary attachment, but you can specify instead that it is text. You can also specify the character set that the file uses if it is text.

Specifically, this method creates an instance of %Net.MailMessagePartOpens in a new tab and places the contents of the file in the BinaryData or TextData property as appropriate, and sets the Charset property and TextData.TranslateTable properties if needed. The method returns, by reference, an integer that indicates the position of this new message part within the Parts array.

This method also sets the Dir and FileName properties of the message or message part.

AttachStream()

method AttachStream(stream As %Stream.Object, 
                    Filename As %String, 
                    isBinary As %Boolean = 1, 
                    charset As %String = "", 
                    ByRef count As %Integer) as %Status {}

Attaches the given stream to the email message. The attachment is considered a file attachment if Filename is specified. Otherwise it is considered an inline attachment. See the comments for AttachFile().

AttachNewMessage()

method AttachNewMessage() as %Net.MailMessagePart {}

Creates a new instance of %Net.MailMessageOpens in a new tab, adds it to the message, and returns the newly modified parent message or message part.

AttachEmail()

method AttachEmail(mailmsg As %Net.MailMessage) {}

Given an email message (an instance of %Net.MailMessageOpens in a new tab), this method adds it to the message. This method also sets the Dir and FileName properties of the message or message part.

Note:

This method sets ContentType to "message/rfc822". In this case, you cannot add any other attachments.

Example: MessageWithAttachment()

The following example generates a simple email message with one hardcoded attachment. It does not provide any addresses for the message; you can provide that information when you actually send the message (see Example 3: SendMessage() in Using an SMTP Server to Send Email).

ClassMethod MessageWithAttachment() As %Net.MailMessage
{
  Set msg = ##class(%Net.MailMessage).%New()
  Set msg.Subject="Message with attachment "_$h
  Set msg.IsBinary=0
  Set msg.IsHTML=0
  Do msg.TextData.Write("This is the main message body.")

  //add an attachment
  Set status=msg.AttachFile("c:\", "GNET.pdf")
  If $$$ISERR(status) {
    Do $System.Status.DisplayError(status)
    Quit $$$NULLOREF
  }
  
  Quit msg
}

For other examples, see the class reference for the %Net.MailMessagePartOpens in a new tab class.

Encoding and Character Translation

A email message part contains information about both the character sets used and the content-transfer-encoding used (if any). For reference, this section describes how this information is used.

For information on character sets and translation tables, see Translation Tables.

%Net.SMTPOpens in a new tab checks the Charset property of each part and then applies the appropriate translation table.

If you do not specify the Charset property for a given part, InterSystems IRIS uses UTF-8.

%Net.SMTPOpens in a new tab also checks the ContentTransferEncoding property. If this property is "base64" or "quoted-printable", then when it creates the message, %Net.SMTPOpens in a new tab encodes the body as needed. (If the content transfer encoding is "7bit" or "7bit", no encoding is needed.)

See Also

• Email Support in InterSystems IRIS

• Sending Email Messages

• Creating and Writing MIME Messages