Version: @(#) $Id: email_message.php,v 1.64 2005/05/01 19:38:40 mlemos Exp $
MIME E-mail message composing and sending
Manuel Lemos (mlemos-at-acm.org)
Copyright © (C) Manuel Lemos 1999-2004
@(#) $Id: email_message.php,v 1.64 2005/05/01 19:38:40 mlemos Exp $
Compose and send e-mail messages according to the MIME standards.
If you are interested in translating the documentation of this class to your own idiom, please contact the author.
Technical support for using this class may be obtained in the mimemessage-dev mailing list. Just go to the mailing list page to browse the list archives, learn how to to join and post support request messages:
http://groups-beta.google.com/group/mimemessage-dev
To used this class just create a new object as follows, set any variables to configure its behavior and call the functions you need to compose and send your messages.
require('email_message.php');
$message_object = new email_message_class;
- Set the sender and recipients
You can set the message sender and one or more recipient addresses using the SetHeader or the SetEncodedEmailHeader functions specifying the addresses for the From, To, Cc and Bcc headers.
- Formatting text messages
You can use the WrapText to assure that a text message does not have more than 75 columns by breaking the longer lines between words.
If you are composing a reply to another text message, you can use the QuoteText function to conveniently mark the text quoted from the original message.
- Add a plain text message body
If the text of the message that you want to send only contains ASCII characters (7 bits), use the AddPlainTextPart function to add the text to the message.
- Add a text message with non-ASCII characters
If your message text may contains non-ASCII characters (8 bits or more), use the AddQuotedPrintableTextPart function to add the text to the message.
If the text uses a character set other than ISO-8859-1 (ISO Latin 1), set the default_charset variable to change the default character set.
- Setting the error message bounce address
This class provides a means to specify the address where error messages should be bounced in case it is not possible to deliver a message. That can be done by setting the header Return-Path with the SetHeader function.
- Request message receipt notification
If you would like to be receive an notification when a message that is sent is received, just use the SetHeader function with the Disposition-Notification-To header to specify the address to where you want to receive the notification message.
Keep in mind that this header just expresses that you want to get a receipt notification, but it may be denied or ignored by the recipient, which does not mean the message was not received.
- Avoding temporary delivery failure warning messages
Sometimes it is not possible to deliver a message immediately due to a networking failure or some other problem. In that case, the mail transfer system usually leaves the message in a queue and keeps retrying to deliver the message until it succeeds or it has reached the limit number of days before it gives up. When it gives up the the message is bounced to the return-path address.
However some systems send a warning message to the original sender when it is not delivered after the first few hours. This may be an useful notification when the message is sent by a human but it maybe inconvinient when you are sending messages to many users like for instance newsletters or messages to subscribers of mailing lists.
If you want to hint the mail transfer system to not send temporary delivery failure warning messages, just use the SetHeader function to set the Precedence header to bulk.
Setting this header this way is a convention used by mailing list manager programs precisely for this purpose. It may also hint some mail receiving systems to not send auto-response messages, for instance when the recipient user is away on vaction. However, not all systems are aware of this convention and still send auto-response messages when you set this header.
- Send the message
Once you have set the message sender, the recipients and added the message text, use the Send function to send the message. This class uses the PHP function mail() to send messages.
If for some reason you need to use a different message delivery method, you may use one of the existing sub-classes that are specialized in delivering messages by connecting to an SMTP server or using directly the programs sendmail and qmail.
- Add an HTML message body
If you want to send an HTML message you can use the AddHTMLPart function if it contains only ASCII characters. If it contains non-ASCII characters, you should the AddQuotedPrintableHTMLPart function instead.
- Add alternative text body for HTML messages
Not every e-mail program can display HTML messages. Therefore, when you send an HTML message, you should also include an alternative text part to be displayed by programs that do not support HTML messages.
This is achieved by composing multipart/alternative messages. This type of message is composed by creating the HTML message part with the CreateHTMLPart or the CreateQuotedPrintableHTMLPart functions, then create the alternative text part with the CreatePlainTextPart or the CreateQuotedPrintableTextPart functions, and finally use the AddAlternativeMultipart function to add an assembly of both message parts.
Note that the text part should be the first to be specified in the array of parts passed to the AddAlternativeMultipart function, or else it will not appear correctly.
Despite this procedure adds a little complexity to the process of sending HTML messages, it is the same procedure that is followed by e-mail programs that are used by most people to send HTML messages.
Therefore, you are strongly recommended to follow the same procedure because some of the modern spam filter programs discard HTML messages without an alternative plain text part, as it constitutes a pattern that identifies messages composed by some of the spam sending programs.
- Embed images in HTML messages
One way to show an image in an HTML message is to use <img> tag with src attribute set to the remote site URL of the image that is meant to be displayed. However, since the message recipient user may not be online when they will check their e-mail, an image referenced this way may not appear.
Alternatively, an image file can be embedded in an HTML message using multipart/related message parts. This type of message part is composed by creating the image file part with the CreateFilePart function.
Then use the GetPartContentID function the image part identifier text. Prepend the string 'cid:' to this identifier to form a special URL that should be used in the HTML part to reference the image part like this:
$image_tag = '<img src="cid:' . $message_object->GetPartContentID($image_part) . '">' ;
When you have composed the whole HTML document, create the HTML message part with the CreateHTMLPart or the CreateQuotedPrintableHTMLPart functions, and finally use the CreateRelatedMultipart function to create a message part that can be added to the message with the function AddAlternativeMultipart like HTML messages with alternative text parts described before.
Note that the HTML part must be the first listed in the parts array argument that is passed to the function CreateRelatedMultipart, or else the message may not appear correctly.
Note also that when you are composing an HTML message with embedded images and an alternative text part, first you need to create the multipart/alternative part with the HTML and the text parts using the CreateAlternativeMultipart function, and then you add the multipart/related part to the message with the AddRelatedMultipart function, passing an array of parts that lists first the multipart/alternative part and then the image part created before.
- Attach files to messages
To send a message with attached files, it is necessary to compose a multipart/mixed message. This is a type of message made by a text or HTML part followed by one or more file parts.
If you add multiple parts to a message, this class implicitly turns it into a multipart/mixed message. Therefore you only need to use the function AddFilePart for each file that you want to attach and the class will automatically generate the message treating any parts added after the first as attachments.
- Forward received messages
To forward an e-mail message received from somewhere, just use the function AddMessagePart passing the message complete with the original headers and body data. The message is forwarded as an attachment that most mail programs can display.
- Sending messages to many recipients (mass or bulk mailing)
Sending messages to many recipients is an activity also known as mass or bulk mailing. There are several alternatives for mass mailing. One way consists on specifying all recipient addresses with the Bcc header, separating the addresses with commas (,), or using the SetMultipleEncodedEmailHeader function. This way you only need to send one message that is distributed to all recipients by your mail transfer system.
Unfortunately, many mail account providers like Hotmail, tend to consider messages sent this way as spam because the real recipients addresses are not visible in To of Cc headers. So, this method is no longer a good solution these days.
The alternative is to send a separate message to each recipient by iteratively setting the To header with each recipient address and calling the Send function. This way tends to take too much time and CPU as the number of recipients grow.
When sending messages to many recipients, call the SetBulkMail function to hint the class to optimize the way it works to make the delivery of the messages more efficient and eventually faster.
The actual optimizations that are performed depend on the delivery method that is used by this class or any of its subclasses specialized on the different delivery methods that are supported. Check the documentation of the subclass that you use to learn about the optimizations that are performed, if any.
If you intend to send messages with the same body to all recipients, the class can optimize the generation of the messages and reduce significantly the composition time if you set the cache_body variable to 1.
If you really need to personalize the content of a message part with different text, HTML or file to each recipient, you should use the ReplacePart function to avoid as much as possible the overhead of composing a new message to each of the recipients of the mailing.
Other than that, take a look at the documentation of the this class sub-classes that may be used in your PHP environment, as these may provide more efficient delivery solutions for mass mailing.
- Error handling
Most of the functions of this class that may fail, return an error message string that describes the error that has occurred. If there was no error, the functions return an empty string.
Verifying the return value of all the functions to determine whether there was an error is a tedious task to implement for most developers. To avoid this problem, this class supports cumulative error checking.
Cumulative error checking means that when an error occurs, the class stores the error message in the error variable. Then, when another function that may fail is called, it does nothing and immediately returns the same error message.
This way, the developers only need to check the return value of the last function that is called, which is usually the Send function.
string
'^([-!#$%&\'*+./0-9=?A-Z^_`a-z{|}~])+@([-!#$%&\'*+/0-9=?A-Z^_`a-z{|}~]+\\.)+[a-zA-Z]{2,6}$'
Specify the regular expression that is used by the ValidateEmailAddress function to verify whether a given e-mail address may be valid.
Do not change this variable unless you have reason to believe that it is rejecting existing e-mail addresses that are known to be valid.
string
'http://www.phpclasses.org/mimemessage $Revision: 1.64 $'
Specify the base text that is used identify the name and the version of the class that is used to send the message by setting an implicit the X-Mailer message header. This is meant mostly to assist on the debugging of delivery problems.
Change this to set another mailer identification string or set it to an empty string to prevent that the X-Mailer header be added to the message.
string
'mail'
Specify the text that is used to identify the mail delivery class or sub-class. This text is appended to the X-Mailer header text defined by the mailer variable.
This variable should only be redefined by the different mail delivery sub-classes.
string
'ISO-8859-1'
Specify the default character set to be assumed for the message headers and body text.
Change this variable to the correct character set name if it is different than the default.
string
'> '
Specify the default line quote prefix text used by the QuoteText function.
Change it only if you prefer to quote lines marking them with a different line prefix.
int
8000
Specify the length of the buffer that is used to read files in chunks of limited size.
The default value may be increased if you have plenty of memory and want to benefit from additional speed when processing the files that are used to compose messages.
string
''
Specify the name of a function that is called whenever an error occurs.
If you need to track the errors that may happen during the use of the class, set this variable to the name of a callback function. It should take only one argument that is the error message. When this variable is set to an empty string, no debug callback function is called.
bool
0
Specify whether the message bodies that are generated by the class before sending, should be cached in memory to be reused on the next message delivery.
Set this variable to 1 if you intend to send the a message with the same body to many recipients, so the class avoids the overhead of regenerating messages with the same content.
string
''
Store the last error return by any function that may fail due to some error.
Do not change this variable value unless you intend to clear the error status by setting it to an empty string.
bool ValidateEmailAddress(
Determine whether a given e-mail address may be valid.
Just pass the e-mail address to be checked as function argument. This function uses the regular expression defined by the email_regular_expression variable to check the address.
address - Specify the e-mail address to be validated.
The function returns 1 if the specified address may be valid.
string WrapText(
Split a text in lines that do not exceed the length limit avoiding to break it in the middle of any words.
Just pass the text to be wrapped.
text - Text to be wrapped.
line_length - Line length limit. Pass a value different than 0 to use a line length limit other than the default of 75 characters.
line_break - Character sequence that is used to break the lines longer than the length limit. Pass a non-empty to use a line breaking sequence other than the default "\n".
line_prefix - Character sequence that is used to insert in the beginning of all lines.
The wrapped text eventually broken in multiple lines that do not exceed the line length limit.
string QuoteText(
Mark a text block to appear like in reply messages composed with common e-mail programs that include text from the original message being replied.
Just pass the text to be marked as a quote.
text - Text to be quoted.
quote_prefix - Character sequence that is inserted in the beginning of all lines as a quote mark. Set to an empty string to tell the function to use the default specified by the line_quote_prefix variable.
The quoted text with all lines prefixed with a quote prefix mark.
string SetHeader(
Set the value of a message header.
Use this function to set the values of the headers of the message that may be needed. There are some message headers that are automatically set by the class when the message is sent. Others must be defined before sending. Here follows the list of the names of the headers that must be set before sending:
Message subject - Subject
Sender address - From
Recipient addresses - To, Cc and Bcc
Each of the recipient address headers may contain one or more addresses. Multiple addresses must be separated by a comma and a space.
Return path address - Return-Path
Optional header to specify the address where the message should be bounced in case it is not possible to deliver it.
In reality this is a virtual header. This means that adding this header to a message will not do anything by itself. However, this class looks for this header to adjust the message delivery procedure in such way that the Message Transfer Agent (MTA) system is hinted to direct any bounced messages to the address specified by this header.
Note that under some systems there is no way to set the return path address programmatically. This is the case when using the PHP mail() function under Windows where the return path address should be set in the php.ini configuration file.
Keep in mind that even when it is possible to set the return path address, the systems of some e-mail account providers may ignore this address and send bounced messages to the sender address. This is a bug of those systems. There is nothing that can be done other than complain.
header - Name of the header.
value - Text value for the header.
encoding_charset - Character set used in the header value. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string SetEncodedHeader(
The same as the SetHeader function assuming the default character set specified by the default_charset variable.
See the SetHeader function.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string SetEncodedEmailHeader(
Set the value of an header that is meant to represent the e-mail address of a person or entity with a known name. This is meant mostly to set the From, To, Cc and Bcc headers.
Use this function like the SetHeader specifying the e-mail address as header value and also specifying the name of the known person or entity.
header - Name of the header.
address - E-mail address value.
name - Person or entity name associated with the specified e-mail address.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string SetMultipleEncodedEmailHeader(
Set the value of an header that is meant to represent a list of e-mail addresses of names of people or entities. This is meant mostly to set the To, Cc and Bcc headers.
Use this function specifying the header and all the addresses in an associative array that should have the email addresses as entry indexes and the name of the respective people or entities as entry values.
header - Name of the header.
addresses - List of all email addresses and associated person or entity names.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
$message_object->SetMultipleEncodedEmailHeader('Bcc', array(
'peter@gabriel.org' => 'Peter Gabriel',
'paul@simon.net' => 'Paul Simon',
'mary@chain.com' => 'Mary Chain'
);
ResetMessage()
Restore the content of the message to the initial state when the class object is created, i.e. without any headers or body parts.
Use this function if you want to start composing a completely new message.
string AddPart(
Add a previously created part to the message.
Use any of the functions to create standalone message parts and then use this function to add them to the message.
part - Number of the part as returned by the function that originally created it.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string ReplacePart(
Replace a message part already added to the message with a newly created part. The replaced part gets the definition of the replacing part. The replacing part is discarded and its part number becomes free for creation of a new part.
Use one of the functions to create message parts and then pass the returned part numbers to this function.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreatePlainTextPart(
Create a plain text message part.
Pass an ASCII (7 bits) text string and get the created part number in the part that is returned by reference.
text - Text of the message part to create.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddPlainTextPart(
Add a plain text part to the message.
Pass an ASCII (7 bits) text string.
text - Text of the message part to add.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateQuotedPrintableTextPart(
Create a text message part that may contain non-ASCII characters (8 bits or more).
Pass a text string and get the created part number in the part that is returned by reference.
text - Text of the message part to create.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddQuotedPrintableTextPart(
Add a text part to the message that may contain non-ASCII characters (8 bits or more).
Pass a text string.
text - Text of the message part to create.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateHTMLPart(
Create an HTML message part only with ASCII characters (7 bit).
Pass an ASCII (7 bits) html text string and get the created part number in the part that is returned by reference.
html - HTML of the message part to create.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddHTMLPart(
Add an HTML part to the message only with ASCII characters.
Pass an html text string.
html - HTML of the message part to create.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateQuotedPrintableHTMLPart(
Create an HTML message part that may contain non-ASCII characters (8 bits or more).
Pass a html text string and get the created part number in the part that is returned by reference.
html - HTML of the message part to create.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddQuotedPrintableHTMLPart(
Add an HTML part to the message that may contain non-ASCII characters (8 bits or more).
Pass a html text string.
html - HTML of the message part to create.
charset - Character set used in the part text. If it is set to an empty string, it is assumed the character set defined by the default_charset variable.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateFilePart(
Create a message part to be handled as a file.
Pass a file definition associative array and get the created part number in the part that is returned by reference.
file - Associative array to specify parameters that describe the file part. Here follows the list of supported parameters that should be used as indexes of the array:
FileName
Name of the file from which the part data will be read when the message is generated. It may be a remote URL as long as your PHP installation is configured to allow accessing remote files with the fopen() function.
Data
String that specifies the data of the file. This should be used as alternative data source to FileName for passing data available in memory, like for instance files stored in a database that was queried dynamically and the file contents was fetched into a string variable.
Name
Name of the file that will appear in the message. If this parameter is missing the base name of the FileName parameter is used, if present.
Content-Type
Content type of the part: text/plain for text, text/html for HTML, image/gif for GIF images, etc..
There is one special type named automatic/name that may be used to tell the class to try to guess the content type from the file name. Many file types are recognized from the file name extension. If the file name extension is not recognized, the default for binary data application/octet-stream is assumed.
Disposition
Information to whether this file part is meant to be used as a file attachment or as a part meant to be displayed inline, eventually integrated with another related part.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddFilePart(
Add a message part to be handled as a file.
Pass a file definition associative array.
file - Associative array to specify parameters that describe the file part. See the file argument description of the CreateFilePart function for an explanation about the supported file parameters.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateMessagePart(
Create a message part to encapsulate another message. This is usually meant to create an attachment that contains a message that was received and is being forwarded intact with the original the headers and body data.
This function should be used like the CreateFilePart function, passing the same parameters to the message argument.
The message to be encapsulated can be specified either as an existing file with the FileName parameter, or as string of data in memory with the Data parameter.
The Content-Type and Disposition file parameters do not need to be specified because they are overridden by this function.
message - Associative array that specifies definition parameters of the message file part.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddMessagePart(
Add a message part that encapsulates another message. This is usually meant to add an attachment that contains a message that was received and is being forwarded intact with the original the headers and body data.
This function should be used like the AddFilePart function, passing the same parameters to the message argument. See the CreateFilePart function for more details.
message - Associative array that specifies definition parameters of the message file part.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateAlternativeMultipart(
Create a message part composed of multiple parts that can be displayed by the recipient e-mail program in alternative formats.
This is usually meant to create HTML messages with an alternative text part to be displayed by programs that cannot display HTML messages.
Create all the alternative message parts that are going to be sent and pass their numbers to the parts array argument.
The least sophisticated part, usually the text part, should appear first in the parts array because the e-mail programs that support displaying more sophisticated message parts will pick the last part in the message that is supported.
parts - Array with the numbers with all the alternative parts.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddAlternativeMultipart(
Add a message part composed of multiple parts that can be displayed by the recipient e-mail program in alternative formats.
This is usually meant to create HTML messages with an alternative text part to be displayed by programs that cannot display HTML messages.
Create all the alternative message parts that are going to be sent and pass their numbers to the parts array argument.
The least sophisticated part, usually the text part, should appear first in the parts array because the e-mail programs that support displaying more sophisticated message parts will pick the last part in the message that is supported.
parts - Array with the numbers with all the alternative parts.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateRelatedMultipart(
Create a message part that groups several related parts.
This is usually meant to group an HTML message part with images or other types of files that should be embedded in the same message and be displayed as a single part by the recipient e-mail program.
Create all the related message parts that are going to be sent and pass their numbers to the parts array argument.
When using this function to group an HTML message with embedded images or other related files, make sure that the HTML part number is the first listed in the parts array argument, or else the message may not appear correctly.
parts - Array with the numbers with all the related parts.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddRelatedMultipart(
Add a message part that groups several related parts.
This is usually meant to group an HTML message part with images or other types of files that should be embedded in the same message and be displayed as a single part by the recipient e-mail program.
Create all the related message parts that are going to be sent and pass their numbers to the parts array argument.
When using this function to group an HTML message with embedded images or other related files, make sure that the HTML part number is the first listed in the parts array argument, or else the message may not appear correctly.
parts - Array with the numbers with all the related parts.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string CreateMixedMultipart(
Create a message part that groups several independent parts.
Usually this is meant compose messages with one or more file attachments. However, it is not necessary to use this function as the class implicitly creates a multipart/mixed message when more than one part is added to the message.
Create all the independent message parts that are going to be sent and pass their numbers to the parts array argument.
parts - Array with the numbers with all the related parts.
part - Number of the created part that is returned by reference.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string AddMixedMultipart(
Add a message part that groups several independent parts.
Usually this is meant compose messages with one or more file attachments. However, it is not necessary to use this function as the class implicitly creates a multipart/mixed message when more than one part is added to the message.
Create all the independent message parts that are going to be sent and pass their numbers to the parts array argument.
parts - Array with the numbers with all the related parts.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
string GetPartContentID(
Retrieve the content identifier associated to a given message part.
Create a message part and pass its number to the part argument.
This function is usually meant to create an URL that can be used in an HTML message part to reference related parts like images, CSS (Cascaded Style Sheets), or any other type of files related to the HTML part that are embedded in the same message as part of a multipart/related composite part.
To use the part content identifier returned by this function you need to prepend the string 'cid:' to form a special URL that can be used in the HTML document this part file.
You may read more about using this function in the class usage section about embedding images in HTML messages.
part - Number of the part as returned by the function that originally created it.
The content identifier text string.
If it is specified an invalid message part, this function returns an empty string.
string GetDataURL(
Generate a data: URL according to the RFC 2397 suitable for using in HTML messages to represent an image or other type of file on which the data is directly embedded in the HTML code instead of being fetched from a separate file or remote URL.
Note that not all e-mail programs are capable of displaying images or other types of files embedded in HTML messages this way.
Pass a file part definition array like for the CreateFilePart function.
file - File definition.
The data: representing the described file or an empty string in case there was an error.
string Send()
Send a composed message.
Use this function after you have set the necessary message headers and added the message body parts.
An error message in case there was an error or an empty string otherwise. This return value may be safely ignored if the function parameters are set correctly.
bool Mail(
Emulate the PHP mail() function by composing and sending a message given the same arguments.
This is mostly meant to provide a solution for sending messages with alternative delivery methods provided by this class sub-classes. It uses the same arguments as the PHP mail() function. Developers willing to use this alternative do not need to change much their scripts that already use the mail() function.
Use this function passing the same arguments as to PHP mail() function.
to - Recipient e-mail address.
subject - Message subject.
message - Message body.
additional_headers - Text string headers and the respective values. There should be one header and value per line with line breaks separating each line.
additional_parameters - Text string with additional parameters. In the original PHP mail() function these were actual switches to be passed in the sendmail program invocation command line. This function only supports the -f switch followed by an e-mail address meant to specify the message bounce return path address.
If this function succeeds, it returns 1.
bool SetBulkMail(
Hint the class to adjust itself in order to send individual messages to many recipients more efficiently.
Call this function before starting sending messages to many recipients passing 1 to the on argument. Then call this function again after the bulk mailing delivery has ended passing passing 1 to the on argument.
on - Boolean flag that indicates whether a bulk delivery is going to start if set to 1 or that the bulk delivery has ended if set to 0.
If this function succeeds, it returns 1.