Qore MailMessage Module Reference  1.3.3
MailMessage::Message Class Reference

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

Public Member Methods

list< stringaddBCC (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< stringaddCC (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< stringaddTO (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< AttachmentgetAttachments ()
 returns a list of Attachment objects for the Message
 
list< stringgetBCC ()
 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< stringgetCC ()
 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< PartgetParts ()
 returns a list of non-attachment Part objects for the Message More...
 
list< stringgetRecipients ()
 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< stringgetTO ()
 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:

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:

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
recipientthe email address to send the message to (bcc)
Returns
the list of "BCC:" addresses
Exceptions
MESSAGE-ADDBCC-ERRORthe recipient's email address is invalid

◆ addBody() [1/2]

MailMessage::Message::addBody ( binary  bin)

concatenates a binary object to the message body

Parameters
binthe binary object to concatenate to the Message body
Exceptions
BODY-ERRORcannot concatenate a binary object to a string body

◆ addBody() [2/2]

MailMessage::Message::addBody ( string  str)

concatenates a string to the message body

Parameters
strthe string to concatenate to the Message body
Exceptions
BODY-ERRORcannot 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
recipientthe email address to send the message to (cc)
Returns
the list of "CC:" addresses
Exceptions
MESSAGE-ADDCC-ERRORthe recipient's email address is invalid

◆ addHeader() [1/3]

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

adds a hash of headers to the Message

Parameters
hdrsa 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
hdrsa 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
hdra 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
recipientthe email address to send the message to
Returns
the list of "To:" addresses
Exceptions
MESSAGE-ADDTO-ERRORthe recipient's email address is invalid

◆ attach() [1/2]

MailMessage::Message::attach ( Attachment  att)

adds an Attachment to the Message

Parameters
attthe 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
namethe name of the attachment to be displayed in the message, normally a file name without any path
mimethe mime type for the message
attthe attachment itself
encthe encoding type for the message (see Message Encodings for possible values)
hdroptional headers for the MIME part for the attachment
Exceptions
UNKNOWN-ENCODINGthe message encoding value passed is unknown/unimplemented
INVALID-ENCODINGthe 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
datathe data to be encoded
encthe encoding type for the data (see Message Encodings for possible values)
noneokif 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-ENCODINGthe message encoding value passed is unknown/unimplemented
INVALID-ENCODINGthe 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-ERRORthe 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
msgthe raw message text as received
Exceptions
MESSAGE-PARSE-ERRORinvalid 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
senderthe sender's email address; can be in the format "Full Display Name <[email protected]>"
subjectthe subject line for the email; the subject will be encoded with "Q" encoding
smtp_modeif True then a single "." will not be serialized alone on a line
Exceptions
MESSAGE-CONSTRUCTOR-ERRORthe 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
hdrthe header to encode (ex: "Subject")
valthe value to encode
eolthe End-Of-Line marker for the string
encodeencode 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
datathe data to encode
encthe encoding type for the data (see Message Encodings for possible values)
hdra reference to a hash for header information
Exceptions
ENCODE-TRANSFER-DATA-ERRORunknown encoding passed

◆ getHeaderString()

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

returns a string of the message headers

Parameters
eolthe End-Of-Line marker for the string
encodeencode 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
msgthe text to process; the first line found will be removed from this argument as well
posthe byte position to update
Returns
the first "\r\n" terminated line from the argument
Exceptions
MESSAGE-PARSE-ERRORinvalid 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
hdra string representing a single line in a Message header
decodedecode any Q or B encoded header words (RFC 2047)
Returns
a single key - value hash for the header
Exceptions
HEADER-ERRORno ':' 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-ERRORthe 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
bodythe Message body to set
encthe encoding type for the message (see Message Encodings for possible values)
content_typethe Content-Type for the message body, if any
Exceptions
UNKNOWN-ENCODINGthe 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
hdrsa 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
hdrsa list of Message header strings to set (replaces all message headers with the given list of strings)
Exceptions
HEADER-ERRORno ':' 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
hdra single string giving a single Message header to set (replaces all message headers with the given string)
Exceptions
HEADER-ERRORno ':' 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_bodyif True the Message body will be included in the string output