The Message class holds the information for a single email Message. More...

#include <MailMessage.qm.dox.h>

Public Member Methods
list< string >	addBCC (string recipient)
	add a recipient to the Message's bcc list More...

	addBody (binary bin)
	concatenates a binary object to the message body More...

	addBody (string str)
	concatenates a string to the message body More...

list< string >	addCC (string recipient)
	add a recipient to the Message's cc list More...

	addHeader (hash< auto > hdrs)
	adds a hash of headers to the Message More...

	addHeader (list< auto > hdrs)
	adds a list of headers to the Message More...

	addHeader (string hdr)
	adds a header to the Message More...

list< string >	addTO (string recipient)
	add a recipient to the Message's recipient list More...

	attach (Attachment att)
	adds an Attachment to the Message More...

	attach (string name, string mime, data att, string enc=EncBase64, *hash< auto > hdr)
	creates an attachment for the Message More...

	checkSendPossible ()
	throws a `MESSAGE-ERROR` exception if the Message cannot be sent More...

	constructor (string msg)
	creates a Message object from raw message text from a received email message More...

	constructor (string sender, string subject, bool smtp_mode=True)
	creates a Message object from the arguments given More...

list< Attachment >	getAttachments ()
	returns a list of Attachment objects for the Message

list< string >	getBCC ()
	returns the list of "BCC:" addresses

*data	getBody ()
	returns the Message body

string	getBodyTransferEncoding ()
	returns the transfer encoding for the mssage body (see Message Encodings for possible values)

list< string >	getCC ()
	returns the list of "CC:" addresses

*string	getFrom ()
	returns the sender's email address

softlist	getHeader ()
	returns the current Message headers as a list of strings

*hash< auto >	getHeaders ()
	returns the current Message headers as a hash

string	getHeaderString (string eol='\r\n', bool encode=True)
	returns a string of the message headers More...

list< Part >	getParts ()
	returns a list of non-attachment Part objects for the Message More...

list< string >	getRecipients ()
	return all the email addresses the message will be sent to, a combination of the "To:", "CC:", and "BCC:" lists

*string	getSender ()
	returns the sender's address in display format

string	getSubject ()
	returns the subject of the Message

list< string >	getTO ()
	returns the list of "To:" addresses

bool	important ()
	returns the current importance setting More...

	important (softbool i)
	sets the importance setting More...

bool	receiptDelivery ()
	returns the delivery receipt setting More...

	receiptDelivery (bool arg)
	sets the delivery receipt setting More...

bool	receiptRead ()
	returns the current read delivery receipt setting More...

	receiptRead (bool arg)
	sets the read delivery receipt setting More...

bool	sendPossible ()
	returns True if the message can be sent, False if not More...

string	serialize ()
	serializes the message to a string that can be sent to an SMTP server, for example More...

	setBody (data body, string enc=EncDefault, *string content_type)
	sets or replaces the Message body More...

	setHeader (hash hdrs)
	sets/replaces the list of Message headers from a hash of header info More...

	setHeader (list hdrs)
	sets/replaces the list of Message headers from a list of header strings More...

	setHeader (string hdr)
	sets/replaces the Message headers More...

string	toLine ()
	returns a single line string summarizing the Message More...

string	toString (bool include_body=False)
	returns a multi-line string representing the Message More...

Static Public Member Methods
static bool	checkEmailAddress (string str)
	returns True if the string contains an email address, False if not

static string	checkEncoding (data data, string enc, bool noneok=False)
	checks the data against the encoding and returns the new encoding (if the encoding is EncDefault for example) More...

static string	doHeaderValue (string hdr, string val, string eol='\r\n', bool encode=True)
	encodes a header value according to the parameters More...

static string	encodeData (data data, string mime, string disp, string enc)
	returns a string of message data according to the encoding passed

static string	encodeTransferData (data data, string enc, reference< hash > hdr)
	returns a string of message data according to the encoding passed More...

static *string	getEmailAddress (string str)
	fetch the email address out of a sender/rcpt string

static string	getLine (reference< string > msg, reference< int > pos)
	returns the first `"\r\n"` terminated line from the argument, updates the byte position argument More...

static hash	parseHeader (string hdr, bool decode=True)
	parses the given string representing a header line and returns a single key - value hash for the header More...

Public Attributes
string	mpboundary = replace(make_base64_string(string(now_us())), "=", "")
	create a different multipart boundary string every time based on the current time

Detailed Description

The Message class holds the information for a single email Message.

Example:: my MailMessage::Message msg("The Sender <[email protected]>", "My Subject");

msg.setBody(body);

msg.addTO("My Best Friend <[email protected]>");

Each message must have a body and at least one destination address before it can be sent.

Set the body text with:

Message::setBody(): set/replace the message body
Message::addBody(): or add a line to the body with

Add recipients with:

Each of the above methods takes email addresses like the sender address in Message::constructor()

To get a text summary of the Message; try:

Message::toString(): returns a multi-line summary of the message for display purposes
Message::toLine(): returns a single line summary of the message for display purposes

Additional header lines (eg: "X-SPAM-Status: No") can be added with addHeader(string) or set with setHeader()

For example, to set the messageid:

m.addHeader("Message-ID: <[email protected]>");

Other useful methods:

attach(): add attachments
important(): sets the given importance or returns the current setting (depending on the variant used)
receiptDelivery(): sets the delivery receipt or returns the current setting (depending on the variant used)
receiptRead(): sets the read receipt request or returns the setting (depending on the variant used)

Member Function Documentation

◆ addBCC()

list< string > MailMessage::Message::addBCC ( string recipient )

add a recipient to the Message's bcc list

Parameters

recipient the email address to send the message to (bcc)

Returns: the list of "BCC:" addresses

Exceptions

MESSAGE-ADDBCC-ERROR the recipient's email address is invalid

◆ addBody() [1/2]

MailMessage::Message::addBody ( binary bin )

concatenates a binary object to the message body

Parameters

bin	the binary object to concatenate to the Message body

Exceptions

BODY-ERROR cannot concatenate a binary object to a string body

◆ addBody() [2/2]

MailMessage::Message::addBody ( string str )

concatenates a string to the message body

Parameters

str	the string to concatenate to the Message body

Exceptions

BODY-ERROR cannot concatenate a string to a binary body

◆ addCC()

list< string > MailMessage::Message::addCC ( string recipient )

add a recipient to the Message's cc list

Parameters

recipient the email address to send the message to (cc)

Returns: the list of "CC:" addresses

Exceptions

MESSAGE-ADDCC-ERROR the recipient's email address is invalid

◆ addHeader() [1/3]

MailMessage::Message::addHeader ( hash< auto > hdrs )

adds a hash of headers to the Message

Parameters

hdrs	a hash of headers to add to the Message

Note: headers for importance, delivery receipt and read receipt will be added automatically and should not be included here

◆ addHeader() [2/3]

MailMessage::Message::addHeader ( list< auto > hdrs )

adds a list of headers to the Message

Parameters

hdrs	a list of headers to add to the Message

Note: headers for importance, delivery receipt and read receipt will be added automatically and should not be included here

◆ addHeader() [3/3]

MailMessage::Message::addHeader ( string hdr )

adds a header to the Message

Parameters

hdr	a header to add to the Message

Note: headers for importance, delivery receipt and read receipt will be added automatically and should not be included here

◆ addTO()

list< string > MailMessage::Message::addTO ( string recipient )

add a recipient to the Message's recipient list

Parameters

recipient the email address to send the message to

Returns: the list of "To:" addresses

Exceptions

MESSAGE-ADDTO-ERROR the recipient's email address is invalid

◆ attach() [1/2]

MailMessage::Message::attach ( Attachment att )

adds an Attachment to the Message

Parameters

att	the Attachment to add to the Message

◆ attach() [2/2]

MailMessage::Message::attach	(	string	name,
		string	mime,
		data	att,
		string	enc = `EncBase64`,
		*hash< auto >	hdr
	)

creates an attachment for the Message

Parameters

name	the name of the attachment to be displayed in the message, normally a file name without any path
mime	the mime type for the message
att	the attachment itself
enc	the encoding type for the message (see Message Encodings for possible values)
hdr	optional headers for the MIME part for the attachment

Exceptions

UNKNOWN-ENCODING	the message encoding value passed is unknown/unimplemented
INVALID-ENCODING	the encoding given cannot be used with data given

◆ checkEncoding()

static string MailMessage::Message::checkEncoding	(	data	data,
		string	enc,
		bool	noneok = `False`
	)

static

checks the data against the encoding and returns the new encoding (if the encoding is EncDefault for example)

Parameters

data	the data to be encoded
enc	the encoding type for the data (see Message Encodings for possible values)
noneok	if this argument is True, then EncNone may be given as an argument

Returns: the new encoding to use in case the input data was EncDefault

Exceptions

UNKNOWN-ENCODING	the message encoding value passed is unknown/unimplemented
INVALID-ENCODING	the encoding given cannot be used with data given

◆ checkSendPossible()

MailMessage::Message::checkSendPossible ( )

throws a MESSAGE-ERROR exception if the Message cannot be sent

To be able to send a message, there must be at least one recipient in the "To:" or the "CC:" or the "BCC:" lists and there must be a message body

See also: sendPossible()

Exceptions

MESSAGE-ERROR the message is incomplete and cannot be sent

◆ constructor() [1/2]

MailMessage::Message::constructor ( string msg )

creates a Message object from raw message text from a received email message

Parameters

msg	the raw message text as received

Exceptions

MESSAGE-PARSE-ERROR invalid message data

◆ constructor() [2/2]

MailMessage::Message::constructor	(	string	sender,
		string	subject,
		bool	smtp_mode = `True`
	)

creates a Message object from the arguments given

This variant of the constructor is designed to be used to create a Message object for sending with the SmtpClient class

Use the Message::addTo() method to add message recipients

Parameters

sender	the sender's email address; can be in the format `"Full Display Name <[email protected]>"`
subject	the subject line for the email; the subject will be encoded with "Q" encoding
smtp_mode	if True then a single "." will not be serialized alone on a line

Exceptions

MESSAGE-CONSTRUCTOR-ERROR the sender's email address is not valid; the subject is empty

◆ doHeaderValue()

static string MailMessage::Message::doHeaderValue	(	string	hdr,
		string	val,
		string	eol = `'\r\n'`,
		bool	encode = `True`
	)

static

encodes a header value according to the parameters

Parameters

hdr	the header to encode (ex: `"Subject"`)
val	the value to encode
eol	the End-Of-Line marker for the string
encode	encode non-ASCII values with quoted printable encoding (http://tools.ietf.org/html/rfc2047)

Returns: a header string (ex: "Subject: =?UTF-8?Q?testing?=\r\n")

◆ encodeTransferData()

static string MailMessage::Message::encodeTransferData	(	data	data,
		string	enc,
		reference< hash >	hdr
	)

static

returns a string of message data according to the encoding passed

Parameters

data	the data to encode
enc	the encoding type for the data (see Message Encodings for possible values)
hdr	a reference to a hash for header information

Exceptions

ENCODE-TRANSFER-DATA-ERROR unknown encoding passed

◆ getHeaderString()

string MailMessage::Message::getHeaderString	(	string	eol = `'\r\n'`,
		bool	encode = `True`
	)

returns a string of the message headers

Parameters

eol	the End-Of-Line marker for the string
encode	encode non-ASCII values with quoted printable encoding (http://tools.ietf.org/html/rfc2047)

Returns: a string with all the message headers separated by the EOL marker

◆ getLine()

static string MailMessage::Message::getLine	(	reference< string >	msg,
		reference< int >	pos
	)

static

returns the first "\r\n" terminated line from the argument, updates the byte position argument

Parameters

msg	the text to process; the first line found will be removed from this argument as well
pos	the byte position to update

Returns: the first "\r\n" terminated line from the argument

Exceptions

MESSAGE-PARSE-ERROR invalid message data

◆ getParts()

list< Part > MailMessage::Message::getParts ( )

returns a list of non-attachment Part objects for the Message

these could represent alternative representations of the message body, for example

◆ important() [1/2]

bool MailMessage::Message::important ( )

returns the current importance setting

if this is True, then the following headers will be sent:

Importance: high
X-Priority: 1
Priority: Urgent

◆ important() [2/2]

MailMessage::Message::important ( softbool i )

sets the importance setting

if this is True, then the following headers will be sent:

Importance: high
X-Priority: 1
Priority: Urgent

◆ parseHeader()

static hash MailMessage::Message::parseHeader	(	string	hdr,
		bool	decode = `True`
	)

static

parses the given string representing a header line and returns a single key - value hash for the header

Parameters

hdr	a string representing a single line in a Message header
decode	decode any Q or B encoded header words (RFC 2047)

Returns: a single key - value hash for the header

Exceptions

HEADER-ERROR no ':' separator character found in header, no key or value found

◆ receiptDelivery() [1/2]

bool MailMessage::Message::receiptDelivery ( )

returns the delivery receipt setting

if this is True, then the following header will be sent:

Disposition-Notification-To: <sender's email address>

◆ receiptDelivery() [2/2]

MailMessage::Message::receiptDelivery ( bool arg )

sets the delivery receipt setting

if this is True, then the following header will be sent:

Disposition-Notification-To: <sender's email address>

◆ receiptRead() [1/2]

bool MailMessage::Message::receiptRead ( )

returns the current read delivery receipt setting

if this is True, then the following header will be sent:

Return-Receipt-To: <sender's email address>

◆ receiptRead() [2/2]

MailMessage::Message::receiptRead ( bool arg )

sets the read delivery receipt setting

if this is True, then the following header will be sent:

Return-Receipt-To: <sender's email address>

◆ sendPossible()

bool MailMessage::Message::sendPossible ( )

returns True if the message can be sent, False if not

To be able to send a message, there must be at least one recipient in the "To:" or the "CC:" or the "BCC:" lists and there must be a message body

Returns: True if the message can be sent, False if not

See also: checkSendPossible()

◆ serialize()

string MailMessage::Message::serialize ( )

serializes the message to a string that can be sent to an SMTP server, for example

Exceptions

MESSAGE-ERROR the message is incomplete and cannot be sent

◆ setBody()

MailMessage::Message::setBody	(	data	body,
		string	enc = `EncDefault`,
		*string	content_type
	)

sets or replaces the Message body

Parameters

body	the Message body to set
enc	the encoding type for the message (see Message Encodings for possible values)
content_type	the Content-Type for the message body, if any

Exceptions

UNKNOWN-ENCODING the message encoding value passed is unknown/unimplemented

◆ setHeader() [1/3]

MailMessage::Message::setHeader ( hash hdrs )

sets/replaces the list of Message headers from a hash of header info

Parameters

hdrs	a hash of Message headers to set (replaces all message headers with the given hash)

Note: headers for importance, delivery receipt and read receipt will be added automatically and should not be included here

◆ setHeader() [2/3]

MailMessage::Message::setHeader ( list hdrs )

sets/replaces the list of Message headers from a list of header strings

Parameters

hdrs	a list of Message header strings to set (replaces all message headers with the given list of strings)

Exceptions

HEADER-ERROR no ':' separator character found in header string

Note: headers for importance, delivery receipt and read receipt will be added automatically and should not be included here

◆ setHeader() [3/3]

MailMessage::Message::setHeader ( string hdr )

sets/replaces the Message headers

Parameters

hdr	a single string giving a single Message header to set (replaces all message headers with the given string)

Exceptions

HEADER-ERROR no ':' separator character found in header string

Note: headers for importance, delivery receipt and read receipt will be added automatically and should not be included here

◆ toLine()

string MailMessage::Message::toLine ( )

returns a single line string summarizing the Message

Returns: a single line string summarizing the Message

◆ toString()

string MailMessage::Message::toString ( bool include_body = False )

returns a multi-line string representing the Message

Parameters

include_body if True the Message body will be included in the string output

Public Member Methods

Static Public Member Methods

Public Attributes

Detailed Description

Member Function Documentation

◆ addBCC()

◆ addBody() [1/2]

◆ addBody() [2/2]

◆ addCC()

◆ addHeader() [1/3]

◆ addHeader() [2/3]

◆ addHeader() [3/3]

◆ addTO()

◆ attach() [1/2]

◆ attach() [2/2]

◆ checkEncoding()

◆ checkSendPossible()

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ doHeaderValue()

◆ encodeTransferData()

◆ getHeaderString()

◆ getLine()

◆ getParts()

◆ important() [1/2]

◆ important() [2/2]

◆ parseHeader()

◆ receiptDelivery() [1/2]

◆ receiptDelivery() [2/2]

◆ receiptRead() [1/2]

◆ receiptRead() [2/2]

◆ sendPossible()

◆ serialize()

◆ setBody()

◆ setHeader() [1/3]

◆ setHeader() [2/3]

◆ setHeader() [3/3]

◆ toLine()

◆ toString()