Working with Received Email
This topic describes how you can work with an email message (%Net.MailMessageOpens in a new tab) that you have received.
Message Basics
After you retrieve an email message (%Net.MailMessageOpens in a new tab), you generally start by determining what kind of message it is and how to read it; that is, whether it is a multipart message and whether the parts are binary. In this step, you can use the ContentType property. Or you can use the IsBinary, IsHTML, and IsMultiPart properties, which indirectly provide the same information as ContentType.
If the message is a multipart message, each part is an instance of %Net.MailMessagePartOpens in a new tab.
Message Headers
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. For example, %Net.MailMessageOpens in a new tab provides properties such as To, From, Subject, and Date. The Headers array property lets you access any custom header; see Specifying Email Message Headers.
Also, if you have retrieved a message via %Net.POP3Opens in a new tab, you can use the GetAttribute() method. Given a header name and an attribute, this method returns the value of that attribute.
Message Contents
Once you know the general message structure, use the following techniques to retrieve the contents:
-
For a multipart message, use the Parts property, which is an array of the parts. Parts.Count() gives you the number of parts. The key for each part is an integer, starting with 1. Use the GetAt() method to retrieve a given part. A message part is an instance of %Net.MailMessagePartOpens in a new tab.
For information on the relationship of %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab, see How InterSystems IRIS Represents MIME Email Messages.
-
For a binary message (or message part), use the BinaryData property.
-
For a text message (or message part), use the TextData property.
-
If IsHTML is 0, the TextData property is an ordinary text string.
-
If IsHTML is 1, the TextData property is an HTML text string.
-
Note that the email client that sends a message determines any wrapping in the message. The mail server has no control over this; nor does InterSystems IRIS.
Other Message Information
The MessageSize property indicates the total length of the message, apart from any attached email messages.
The following methods provide additional information about the message:
Returns the date and time when the message was retrieved, converted to local time in $HOROLOG format.
Returns the date and time when the message was retrieved, converted to UTC in $HOROLOG format.
Returns the date and time when the message was retrieved, in seconds since 12/31/1840.
The following class methods are also available for time/date conversion:
A class method that converts a date/time in $HOROLOG format to seconds since 12/31/1840.
A class method that converts seconds since 12/31/1840 to a date/time in $HOROLOG format.
Example 1: ShowMsgInfo()
Given an instance of %Net.MailMessageOpens in a new tab, the following method writes information about the message to the current device:
ClassMethod ShowMsgInfo(msg as %Net.MailMessage)
{
Write "Message details *****",!
Write "To (count): ", msg.To.Count(),!
Write "From: ", msg.From,!
Write "Cc (count): ", msg.Cc.Count(),!
Write "Bcc (count): ", msg.Bcc.Count(),!
Write "Date: ", msg.Date,!
Write "Subject: ", msg.Subject,!
Write "Sender: ", msg.Sender,!
Write "IsMultipart: ", msg.IsMultiPart,!
Write "Number of parts: ", msg.Parts.Count(),!
Write "Number of headers: ", msg.Headers.Count(),!
Write "IsBinary: ", msg.IsBinary,!
Write "IsHTML: ", msg.IsHTML,!
Write "TextData: ", msg.TextData.Read(),!
Write "BinaryData: ", msg.BinaryData.Read(),!
}
This method produces output similar to the following:
Message details *****
To (count): 1
From: "XXX XXX" <XXX@XXX.com>
Cc (count): 0
Bcc (count): 0
Date: Fri, 16 Nov 2023 11:57:46 -0500
Subject: test 5
Sender:
IsMultipart: 0
Number of parts: 0
Number of headers: 16
IsBinary: 0
IsHTML: 0
TextData: This is test number 5, which is plain text.
BinaryData:
Example 2: ShowMsgPartInfo()
The following method writes information about a part of a message:
ClassMethod ShowMsgPartInfo(msg as %Net.MailMessage, partno as %Integer)
{
Set part=msg.Parts.GetAt(partno)
Write "Message part details *****",!
Write "Message part: ", partno,!
Write "IsMultipart: ", part.IsMultiPart,!
Write "Number of parts: ", part.Parts.Count(),!
Write "Number of headers: ", part.Headers.Count(),!
Write "IsBinary: ", part.IsBinary,!
Write "IsHTML: ", part.IsHTML,!
Write "TextData: ", part.TextData.Read(),!
Write "BinaryData: ", part.BinaryData.Read(),!
}
This produces output similar to the following (given a different message than previously shown):
Message part details *****
Message part: 1
IsMultipart: 0
Number of parts: 0
Number of headers: 2
IsBinary: 0
IsHTML: 0
TextData: 1 test string
BinaryData:
Example 3: ShowMsgHeaders()
The following method writes information about the headers of a message; you could write a similar method that did the same for a message part.
ClassMethod ShowMsgHeaders(msg as %Net.MailMessage)
{
Set headers=msg.Headers
Write "Number of headers: ", headers.Count(),!
//iterate through the headers
Set key=""
For {
Set value=headers.GetNext(.key)
Quit:key=""
Write "Header:",key,!
Write "Value: ",value,!!
}
}
This produces output similar to the following:
Number of headers: 16
Header: content-class
Value: urn:content-classes:message
Header: content-type
Value: multipart/alternative; boundary="----_=_NextPart_001_01C8286D.D9A7F3B1"
Header: date
Value: Fri, 16 Nov 2023 11:29:24 -0500
Header: from
Value: "XXX XXX" <XXX@XXX.com>
Header: message-id
Value: <895A9EF10DBA1F46A2DDB3AAF061ECD501801E86@Exchange1_backup>
Header: mime-version
Value: 1.0
...