MailMessage::Message Class Reference

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

## Public Member Functions

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 n_body, string n_enc=EncDefault, *string n_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 Functions

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 <sender@email.com>", "My Subject");
  msg.setBody(body);
  msg.addTO("My Best Friend <you@friend.com>");

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:

- Message::addTO()
- Message::addCC()
- Message::addBCC()

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: <20090712.123456789@mail.drei.at>");

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 <name@example.com>"`
  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 | n_body,
|  | string | n_enc = `EncDefault`,
|  | *string | n_content_type
| ) |  |

sets or replaces the Message body

Parameters

  n_body | the Message body to set
  n_enc | the encoding type for the message (see Message Encodings for possible values)
  n_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