Mail Message Object

Overview

Contains a message to send or a downloaded message.

E-mail addresses can have three different formats:

• Simple direct address - username@domain.ext. Example: "john@email.com"
• Compound name with address in brackets -
  Name \username@domain.ext\
  Example: "John Smith\john@email.com\"
• Compound comment (name) in parenthesis and address -
  (Comment) username@domain.ext
  Example: "(John Smith) john@email.com"

To send a non-MIME mail message, set the Text property to a text value. Any other method to add a text part or other kinds of data will transform the message into a MIME multi part message and add the value in the Message text to a plain text part. That part will be added as the first part in the message parts.

• Method: Save does not support the Mail_Decoded option.
• Method: Load does not support load of mails saved with the Mail_Decoded option.
• Method: AddText differs in implementation.

note

When a message is not a multi-part message, the message object behaves as having one body part. This body part is the full message body and can be accessed on index 1. For example, if the body only contains an attachment, the attachment can be saved using the SaveBodypartToFile method with the index parameter set to 1.

For detailed descriptions, see topic for each method.

Sections

Init, Main, Procedures, OnExit, and Structure.

note

The object is declared in the Declare section.

Properties

Name	Description
From	Sender (from) address.
ToList	List of receiver addresses.
BccList	List of addresses to receive blind copy of message.
CcList	List of addresses to receive copy of message.
Subject	Message subject text.
Text	Body text. Use only if not a multipart message.
ToString	To addresses separated by ';'.
BccString	Bcc addresses separated by ';'.
CcString	Cc addresses separated by ';'.
MsgNumber	Message number assigned by a POP3 or IMAP server.
MsgUid	Message unique id assigned by a POP3 or IMAP server.
BodyParts	Returns the collection of body parts in the message.
BodypartCount	Number of body parts in message. If message is a multi-part message, body is not included.
BodypartFilename	Returns the body part filename, if any. Normally only attachments have filenames.
HeaderLabel	Message header label in accordance with RFC 2076.
Headers	Returns the collection of header fields contained in a message.
BodypartHeaderLabel	Body part header label in accordance with RFC 2076.
IsSMIME	Gets a value indicating whether the message is in S/Mime format.
ObjectIsEmpty	Returns 1 if object is not created.
LastReturnCode	Returns last known return code from object.

Methods

Name	Description
AddAttachment	Adds an attachment to the message.
AddText	Adds body text to a multipart message.
Save	Saves the message to disk in encoded or decoded format.
Load	Loads a message from disk that has previously been saved to disk with the Save method.
AddHtml	Adds Html body text to the message.
AddHtmlString	Adds HTML body text to the message.
AddMessage	Adds another message as an attachment to the message.
CreateForwardMsg	Creates a new forward message of the message.
CreateReplyMsg	Creates a new reply message of the message.
SaveBodypartToFile	Saves a body part to a disk file.
CreateObject	Creates a new instance of the object.
FreeObject	Releases the current instance of the object.

See also

POP3 Object
SMTP Object
SMTP Object::Send
POP3 Object::DownloadMessages
POP3 Object::Message

Properties

---

From

The sender address of the e-mail message.

Parameters

Type: String
Default: "
Read: get_From
Write: put_From

---

ToList

The receiver addresses of the e-mail message.

Parameters

Type: Simple String List Object
Default: "
Read: get_ToList
Write: put_ToList

See also

Mail Message Object::ToString
Simple String List Object

---

BccList

Addresses to receive a blind copy of the e-mail message (Bcc addresses).

Parameters

Type: Simple String List Object
Default: "
Read: get_BccList
Write: put_BccList

See also

Simple String List Object
Mail Message Object::BccString

---

CcList

Addresses to receive a copy of the e-mail message (Cc addresses).

Parameters

Type: Simple String List Object
Default: "
Read: get_CcList
Write: put_CcList

See also

Mail Message Object::CcString
Simple String List Object

---

Subject

The subject header text of the e-mail message.

Parameters

Type: String
Default: "
Read: get_BccList
Write: put_BccList

---

Text

The body text of the e-mail message. Mainly to be used for non-multipart messages to set message text.

It is not possible to set body text on multi part messages. The text will end up as the first body part of a multi part message. If setting this property in a multi part message, the text will be written into a PlainText part, which will always be the first part of the message. If a PlainText part already exists as the first part of the message, the content of that part will be overwritten.

Parameters

Type: String
Default: "
Read: get_Text (A carriage return and line feed is added at the end of the data.)
Write: put_Text

See also

Mail Message Object::AddText
Mail Message Object::AddHtml

---

ToString

Receiver addresses separated by semicolon (;).

Parameters

Type: String
Default: "
Read: get_ToString
Write: put_ToString

See also

Mail Message Object::ToList

---

BccString

Addresses to receive a blind copy of message (Bcc addresses) separated by semicolon (;).

Parameters

Type: String
Default: "
Read: get_BccString
Write: put_BccString

See also

Mail Message Object::BccString

---

CcString

Addresses to receive a copy of message (Cc addresses) separated by semicolon (;).

Parameters

Type: String
Default: "
Read: get_CcString
Write: put_CcString

See also

Mail Message Object::BccList

---

MsgNumber

Message number assigned by a POP3 or IMAP server. Use as value in MsgSet parameters of methods on a POP3 Object.

Parameters

Type: Integer
Default:
Read: get_MsgNumber
Write:

See also

POP3 Object::DeleteMessages
POP3 Object::DownloadMessages

---

MsgUid

Message unique id assigned by a POP3 or IMAP server.

Parameters

Type: String
Default: "
Read: get_MsgUid
Write:

See also

Mail Message Object::MsgNumber

---

BodyParts

Returns the collection of body parts in the message.

Parameters

Type: Mail Body Parts Object
Default:
Read: get_BodyParts
Write: put_BodyParts

See also

Mail Message Object::BodypartCount Mail Message Object::BodypartFilename Mail Message Object::SaveBodypartToFile

---

BodypartCount

Number of body parts in message. The message body is not included, if the message contains multiple parts.

Parameters

Type: Integer
Default:
Read: get_BodyPartCount
Write:

See also

Mail Message Object::SaveBodypartToFile Mail Message Object::BodyParts Mail Message Object::BodyPartFilename

---

BodypartFilename

Returns the body part filename, if any. Normally, only attachments have filenames, message body does not.

Parameters

Type: Integer
Default:
Read: get_BodyPartFilename
Write:

lIndex	Integer Index of bodypart. Range: 1..BodypartCount
IsAttachment	Pointer to ParamTypeBool True_Value if bodypart is an attachment.
Return value	ParamTypeFilepath The bodypart filename.

See also

Mail Message Object::SaveBodypartToFile
Mail Message Object::BodyParts
Mail Message Object::BodyPartCount

---

HeaderLabel

Message header label in accordance with RFC 2076. Returns an empty string if label is not found.

Parameters

get_HeaderLabel

Label	MailHeaderLabel Type of label to read.
Return value	String The value of the label. Default: "

See also

MailHeaderLabel
Mail Body Part Object::Headers
Mail Message Object::Headers

---

Headers

Collection of header fields contained in a Mail Message Object.

The difference between the Header property associated with the Mail Message Object and the Mail Body Part Object is the treatment of the To, Cc, and Bcc labels. The Mail Message Object has separate properties for these labels, and therefore excludes these labels from the Header property. The Mail Body Part Objects include these labels within this property.

Parameters

get_Headers

Return value: Mail Header Fields Object

put_Headers

Return value: Mail Header Fields Object - Copies headers into the collection.

See also

Mail Message Object::Headerlabel
Mail Body Part Object::Headers

---

BodyPartHeaderLabel

Body part header label in accordance with RFC 2076. Returns an empty string if label is not found.

Parameters

get_BodyPartHeaderLabel

Index	Integer Index of bodypart. Range: 1..BodypartCount
Label	MailHeaderLabel Type of label to read.
Return value	String The value of the label. Default: "

See also

MailHeaderLabel
Mail Message Object::BodyPartCount

---

IsSMIME

---

Parameters

Type:
Default:
Read: get_IsSMIME
Write:

---

Methods

---

AddAttachments

Adds an attachment to the message.

This method provides a simple way to attach a file to a message. The attributes of the file are determined by the file extension, which is used to correctly label and encode the file. Any number of attachments may be added.

Parameters

Filename	Type: ParamTypeFilepath Default: Description: Fully qualified path of the file to attach.

User defined mapping from file type to content type. Refers to all file types.

• Content-Type: application/octet-stream; name="filename.extension"
• Content-Transfer-Encoding: base64
• Content-Disposition: attachment; filename="filename.extension"

---

AddText

Adds body text to a multipart message.

This method is used to add text if the message is multipart. If a non-multipart message is being composed, the Text property can be used instead.

Parameters

Text	Type: String Default: Description: String containing the Text value.

Invoke of AddText always adds a new tex/plain multipart. If message is already not a multipart message, the message is transformed into a multipart message and two text/plain parts are added. The first part holds the value of property Text and the second part holds the value provided in call to AddText.

Also, another call to AddText will add another text/plain part.

See also

Mail Message Object::AddHtml
Mail Message Object::AddMessage
Mail Message Object::Text

---

Save

Saves the message to disk in encoded or decoded format.

Parameters

Filename	Type: ParamTypeFilepath Default: Description: Fully qualified path of the file to be created.
FileFormat	Type: MailFormatConstants Default: MailEncoded Description: File format of the file created. Only FileFormat 'MailEncoded' supported.
ReturnValue	Type: ParamTypeBool Default: Description: Returns True_Value if succeeded.

Remarks

If the FileFormat parameter is 'MailEncoded' or unspecified, the message will be stored as a transport ready file containing the encoded message. If the FileFormat parameter is 'MailDecoded' the message will be stored in an object format. These files are smaller and quicker to read and write then an encoded file.

Decoded files store attached files externally. In addition, data is stored as 8-bit data instead of the 7-bit data used in 'MailEncoded' format. This results in smaller files and there is no decoding required when the file is loaded.

See also

MailFormatConstants
Mail Message Object::Load

---

Load

Loads a message from disk that has previously been saved to disk with the Save method.

This method senses the format of the file (encoded message or object) and initializes the Mail Message Object as the file contents are read.

Parameters

Filename	Type: ParamTypeFilepath Default: Description: Contains the fully qualified filename to be loaded.
Segment	Type: MailSegmentConstants Default: MailSegm_Message Description: Determines how much of the message is to be read from the file.

Remarks

Only FileFormat 'MailEncoded' is supported.

See also

MailSegmentConstants
Mail Message Object::Save

---

AddHtml

Adds html body text to the message.

This method provides an easy way to create a ready-to-send HTML email message. When the method is called, the HTML file specified by Filename is added as a part. The text from this file is also added as a plain text part for any mail reader that cannot read HTML.

All images referenced by the HTML text (using "img" tags) are added as parts to the message. It is not advised to alter the Mail Message object once it has been created using the AddHtml method.

Parameters

Filename	Type: ParamTypeFilepath Default: Description: Fully qualified path of the HTML file to create the message from.

Remarks

Encoding is detected either from the file's byte order mark or from the charset specified by the HTML META tag (if present in the file). If encoding cannot be detected it will default to iso-8859-1.

See also

Mail Message Object::AddHtmlString
Mail Message Object::AddText
Mail Message Object::AddMessage
Mail Message Object::Text

---

AddHtmlString

Adds an HTML string to the message.

Parameters

HtmlText	Type: String Description: Html text string.

See also

Mail Message Object::AddHtml

---

AddMessage

Adds another message as an attachment to the message.

This method provides a simple way to attach an existing message. Any number of existing messages can be added to a Mail Message Object.

Parameters

MailMessage	Type: Mail Message Object Description: Mail message Object to be added.

See also

Mail Message Object::AddText
Mail Message Object::AddHtml
Mail Message Object::CreateForwardMsg

---

CreateForwardMsg

Creates a new forward message of the message to the specified receiver address(es).

Parameters

To	Type: String Default: Description: String containing addresses that the message is to be forwarded to.
ExtraText	Type: String Default: " Description: Introductory text for the forwarded message
ReturnValue	Type: Mail Message Object Default: Description: Mail Message Object created

---

CreateReplyMsg

Creates a new reply message of the message to the sender or to all receiver address(es).

Parameters

NewText	Type: String Default: " Description: The new text for the reply message.
OldTextLeader	Type: String Default: '>' Description: The indent character string for the old message text.
ReturnValue	Type: Mail Message Object Default: Description: Mail Message Object created

See also

Mail Message Object::CreateForwardMsg

---

SaveBodypartToFile

Saves a body part to a disk file.

Parameters

Index	Type: Integer Default: Description: The index of bodypart to save. Range: 1..BodypartCount.
Filename	Type: ParamTypeFilepath Default: Description: The fully qualified path of the file to be created, or empty. See also Remarks below.
ReturnValue	Type: ParamTypeBool Default: Description: Returns True_Value if succeeded.

Remarks

If parameter filename is an empty string, the body part will be save to the predefined directory "ProgramData\iCore Solutions\iCPS\Temp\Mail" with the filename specified in the bodypart (the attachment filename).

For example if the default ProgramData directory is "C:\ProgramData" and the attachment filename is "OrderInfo.xml", the bodypart will be saved as "C:\ProgramData\iCore Solutions\iCPS\Temp\Mail\OrderInfo.xml"

See also

Mail Message Object::BodyParts
Mail Message Object::BodyPartCount
Mail Message Object::BodyPartFilename