Exponent v2.4.3
Back to top  

expMail

The expMail class

package

Subsystems

Methods

__construct() - This function constructs the message to be send in this object, filling it out with connection information based on the site config.

__construct(array $params = array())
author

Tyler Smart tyleresmart@gmail.com
example

can specify how you would like to send mail, overriding the system default.

//Here you are using the system default, whether it is smtp, php mail, sendmail, exim, native, or rotator.

$emailItem = new expMail();

//Here you are trying different types of connections: $emailItem = new expMail(array('method'=>'smtp')); $emailItem = new expMail(array('method'=>'sendmail'); $emailItem = new expMail(array('method'=>'exim'); $emailItem = new expMail(array('method'=>'native'); $emailItem = new expMail(array('method'=>'rotator');
todo

add support for telling the constructor where the system specific Mail Transit Authority is: i.e. where sendmail or exim is if not in the default /usr/sbin

drop support for passing in custom "connections", a Swift 3.x relic that we do not need.

add further documentation for using settings other than the system default

Arguments

$params

array

You can specify which method by which you would like to send mail.

expMail class destructor

__destruct()

addBcc() - This adds Blind Carbon Copy addresses to the message one at a time, so if you want to add multiple BCC's it is best to run through a loop in order to put them in.

addBcc(string $email, string $name = null)
author

Tyler Smart tyleresmart@gmail.com
example

will send a basic message, looping through an array of email addresses add adding them to the BCC list.

$emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$bccs = array('a@website.com'=>'Mr A.', 'b@website.com'=>'Mr B.', 'c@website.com'=>'Mr C.', 'd@website.com'=>'Mr D.', 'e@website.com'=>'Mr E.', 'f@website.com'=>'Mr F.');

//add multiple bcc recipients to the email foreach ($bccs as $email => $name) { $emailItem->addBcc($email, $name); }

$emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); //setting the From field using just the email. $emailItem->subject('Hello World!');

$emailItem->send();

Arguments

$email

string

This is the email address for the BCC.

$name

string

This is the name associated with the above email address.

addCc() - This adds Carbon Copy addresses to the message one at a time, so if you want to add multiple CC's it is best to run through a loop in order to put them in.

addCc(string $email, string $name = null)
author

Tyler Smart tyleresmart@gmail.com
example

will send a basic message, looping through an array of email addresses add adding them to the CC list.

$emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$ccs = array('a@website.com'=>'Mr A.', 'b@website.com'=>'Mr B.', 'c@website.com'=>'Mr C.', 'd@website.com'=>'Mr D.', 'e@website.com'=>'Mr E.', 'f@website.com'=>'Mr F.');

//add multiple cc recipients to the email foreach ($ccs as $email => $name) { $emailItem->addCc($email, $name); }

$emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); //setting the From field using just the email. $emailItem->subject('Hello World!');

$emailItem->send();

Arguments

$email

string

This is the email address for the CC.

$name

string

This is the name associated with the above email address.

addFrom() - This adds the singular From address, if you call it twice, it will replace the old from address.

addFrom(string $email = null)

It also sets the private var from with whatever you desire. This is a relic from the Swift 3.x days and should be gutted out the next time someone upgrades the mailer.

author

Tyler Smart tyleresmart@gmail.com
example

will send a basic message, but you can see how the subject line works. $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); //setting the From field using just the email. $emailItem->addFrom('from@sender.com', 'Mr. Sender'); //resetting the From field using the email and the name. $emailItem->subject('Hello World!'); $emailItem->send();

Arguments

$email

string

This is the email address you want to use as the sender.

addHeaders() - Add text headers to the message. Limited to text headers for now.

addHeaders(array $headers)
author

Tyler Smart tyleresmart@gmail.com
example

will include the passed HTML and will set it as an addition to the message body.

$emailItem = new expMail();

$emailItem->addHTML('

My Text

'); //This adds an alternate version if your email in HTML format

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$headersToAdd = array('Your-Header-Name' => 'the header value', 'SecondHeader-Name' => '2nd header value'); $emailItem->addHeaders($headersToAdd);

$emailItem->send();
todo

add support for other types of headers mentioned below, and a second pass in value/switch to specify what kind headers you are adding

Text Headers

    Text headers are the simplest type of Header. They contain textual information with no special information included within it for example the Subject header in a message.

Parameterized Headers

    Parameterized headers are text headers that contain key-value parameters following the textual content. The Content-Type header of a message is a parameterized header since it contains charset information after the content type.

Date Headers

    Date headers contains an RFC 2822 formatted date (i.e. what PHP's date('r') returns). They are used anywhere a date or time is needed to be presented as a message header.

Mailbox (e-mail address) Headers

    Mailbox headers contain one or more email addresses, possibly with personalized names attached to them. The data on which they are modeled is represented by an associative array of email addresses and names.

ID Headers

    ID headers contain identifiers for the entity (or the message). The most notable ID header is the Message-ID header on the message itself.

Path Headers

    Path headers are like very-restricted mailbox headers. They contain a single email address with no associated name. The Return-Path header of a message is a path header.

Arguments

$headers

array

Array of text headers to add to the message

addHTML() - This function is similar to setHTMLBody except that it includes the HTML in the message body rather than sets it as default. Many mail clients will read the HTML over plain text as default behavior, so even if you use setTextBody and addHTML, they will default to reading the HTML.

addHTML(string $html)

setHTMLBody is to be preferred as the default for setting the body of the email.

author

Tyler Smart tyleresmart@gmail.com
example

will include the passed HTML and will set it as an addition to the message body.

$emailItem = new expMail();

$emailItem->addHTML('

My Text

'); //This adds an alternate version if your email in HTML format

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

You can also call the addHTML multiple times to append to the message:

$emailItem = new expMail();

$emailItem->addHTML('My HTML
'); $emailItem->addHTML('Line Two
'); $emailItem->addHTML('Line Three
');

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Arguments

$html

string

This is the html that you want added to the message.

addRaw() - This is a wrapper around setHTMLBody for backwards compatibility

addRaw( $body)
author

Tyler Smart tyleresmart@gmail.com

Arguments

$body

subject() - This will set the subject of the message, ensuring first that message has been instantiated.

addSubject(string $subj)
author

Tyler Smart tyleresmart@gmail.com
example

will send a basic message, but you can see how the subject line works. $emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

 $emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com'));

$emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Arguments

$subj

string

This is the string that you want to be used as the subject for the message, it must be plain text.

addText() - This function is similar to the addHTML function above, it adds a plain text part to the message in case your recipient cannot receive HTML email, if you have added a text version of the email, they will have this to fall back on.

addText(string $text)

Every email send out should have an HTML version and a TEXT version.

author

Tyler Smart tyleresmart@gmail.com
example

will set the message body in HTML and also include a text counterpart in case the recipient cannot view HTML.

$emailItem = new expMail();

$emailItem->setHTMLBody('My Text '); //This is an HTML version of the message $emailItem->addText('My Text '); //This adds a Text version in case they cannot read HTML

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Arguments

$text

string

This is the text version of the email you are sending along with the HTML

addTo() - This adds people to the Recipient List in the To Field.

addTo(array|string $email = null)

If the first variable passed is an array, it assumes you are sending messages to multiple people. If you want to add people with their names associated with the email, you must use an outside for loop. This function does not yet support the parsing of associative arrays for a quick add to the To recipient list.

author

Tyler Smart tyleresmart@gmail.com
example

will send a basic message, looping through an array of email addresses add adding them to the BCC list. $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $to_array = array('a@website.com'=>'Mr A.', 'b@website.com'=>'Mr B.', 'c@website.com'=>'Mr C.', 'd@website.com'=>'Mr D.', 'e@website.com'=>'Mr E.', 'f@website.com'=>'Mr F.'); //add multiple bcc recipients to the email foreach ($to_array as $email => $name) { $emailItem->addBcc($email, $name); } $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!'); $emailItem->send(); //You can also just specify the email without the name, like so: $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $emailItem->addTo('bob@smith.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!'); $emailItem->send(); //You can also send an array of email addresses as the first argument, like so: $emailItem = new expMail(); $emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three '); $emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!'); $emailItem->send();
todo

A nice future feature addition would be to allow the passing in of associative arrays like so: $emailsToSendTo = array('bob@smith.com'=>'Bob Smith', 'mary@smith.com'=>'Mary Smith'); $emailItem->addTo($emailsToSendTo); OR $emailItem->addTo('array('myemail@mysite.com'=>'Website Owner', 'secondemail@website.com'=>'Frank Jones'); Actually, cleanup should be done so that this function only takes associative arrays, and nothing else.

Arguments

$email

array|string

This is the string or array to send email to

attach_file_on_disk() - This function will utilize the swift mailer's ability to attach files that are on disk, unlike the one above, which just attached one that is available in memory.

attach_file_on_disk(string $file_to_attach, string $file_type)
author

Tyler Smart tyleresmart@gmail.com
example

will show three different ways to attach files, two from a path on disk, and one from a url. //Create the attachment // * Note that you can technically leave the content-type parameter out $attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');

//Attach it to the message
$message->attach($attachment);

//The two statements above could be written in one line instead
$message->attach(Swift_Attachment::fromPath('/path/to/image.jpg'));

//You can attach files from a URL if allow_url_fopen is on in php.ini
$message->attach(Swift_Attachment::fromPath('http://site.tld/logo.png'));

Arguments

$file_to_attach

string

This is the path to the file that you want to attach to the message

$file_type

string

This is the MIME type of the file that you are attaching

batchSend() - Does not seem to be working correctly. Use at your own risk!

batchSend() : void

This should probably be taken out as it look like a failed attempt to use the old-school AntiFlood plugin This is leftover code from Swift 3.x

todo

Update this section to use batch processing properly
author

Tyler Smart tyleresmart@gmail.com

clearBody() - This function will set the body of the message to empty, a blank text string

clearBody()
author

Tyler Smart tyleresmart@gmail.com

flushRecipients() - this will clear all of the recipients in the To array, ignoring CC and BCC

flushRecipients()
author

Tyler Smart tyleresmart@gmail.com
example

will set some recipients and then clear them $emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$emailItem->addTo('bob@smith.com', 'Bob Smith'); $emailItem->addTo('bob2@smith.com', 'Bob2 Smith'); $emailItem->addTo('bob3@smith.com', 'Bob3 Smith');

$emailItem->flushRecipients();

$emailItem->addTo('whataboutbob@smith.com', 'Frank Smith');

$emailItem->send();

messageId() - This will return the unique ID of the mail message.

messageId() : array

Courtesy of the underlying Swift mailer:

ID headers contain identifiers for the entity (or the message). The most notable ID header is the Message-ID header on the message itself.

An ID that exists inside an ID header looks more-or-less less like an email address. For example, 1234955437.499becad62ec2@example.org. The part to the left of the @ sign is usually unique, based on the * current time and some random factor. The part on the right is usually a domain name.

author

Tyler Smart tyleresmart@gmail.com
example

returns the Message ID on the mail

$emailItem = new expMail();

$emailItem->addText('My Text '); $emailItem->addText('Line Two '); $emailItem->addText('Line Three ');

$emailItem->addTo(array('myemail@mysite.com', 'secondemail@website.com', 'third@emailsite.com')); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

echo "$emailItem->messageID()";

$emailItem->send();

Response

array

quickBatchSend() - a quick way to send a batch of emails one at a time This function is similar to quickSend, but sends each email separately to protect others identity in the mailing

quickBatchSend(array $params = array()) : boolean|integer
author

Tyler Smart tyleresmart@gmail.com

Arguments

$params

array

Response

boolean|integer

quickSend() - This is a quick method for sending email messages. It only requires a message value be passed in an associative array, (or else the message fails immediately).

quickSend(array $params = array()) : integer
todo

May add allowing a string param to be passed as the message (text_message) using all defaults to mail it.
author

Tyler Smart tyleresmart@gmail.com
example

will send a quick message, showing you what basic fields are required.

$body = "My body."; $tos = explode(',', str_replace(' ', '', COMMENTS_NOTIFICATION_EMAIL)); //pull list of CSV emails from the site config $subject = "My subject";

$mail = new expMail(); $mail->quickSend(array( 'html_message'=>$body, 'to'=>$tos, 'from'=>trim(SMTP_FROMADDRESS), //pull EMAIL from site config 'subject'=>$subject, ));

(or even simpler) $mail = new expMail(); $mail->quickSend(array('html_message'=>'Hello'));

Arguments

$params

array

This is the associative array required to send the email. The minimum basics for sending an email are: -html_message or -text_message If a from or a to is not specified, the send method will pull the default SMTP_FROMADDRESS from the site config. Usable parameters include: -to -from -subject -html_message -text_message -headers

Response

integer

number of recipients to which the email was successfully sent.

send

send()

setHTMLBody() - This function sets the main version of the message to HTML.

setHTMLBody(string $html)
author

Tyler Smart tyleresmart@gmail.com
example

will set the message body to the HTML that is passed in. This is the standard way to set the email message body.

$emailItem = new expMail();

$emailItem->setHTMLBody('

My Text

'); //This sets the body to be an HTML version

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Arguments

$html

string

This is the HTML that you want set as the body

setTextBody() - This function sets the main version of the message to plain text. No HTML

setTextBody(string $text)
author

Tyler Smart tyleresmart@gmail.com
example

will set the message body to plain text. Usually people do this because the recipient cannot read HTML email.

$emailItem = new expMail();

$emailItem->setTextBody('My Text '); //This adds a Text version in case they cannot read HTML

$emailItem->addTo('myemail@mysite.com'); $emailItem->addFrom('from@sender.com'); $emailItem->subject('Hello World!');

$emailItem->send();

Arguments

$text

string

This is the text version of the email you are sending

test() - Does the mail system seem to be working correctly? This is useless for the Native mail system

test()
todo

Update this section to use more error checking

Properties

to

to :

Type(s)

from

from :

Type(s)

cc

cc :

Type(s)

bcc

bcc :

Type(s)

subject

subject :

Type(s)

message

message :

Type(s)

log

log :

Type(s)

errStack

errStack :

Type(s)

transport

transport :

Type(s)

mailer

mailer :

Type(s)

precallfunction

precallfunction :

Type(s)

precalldata

precalldata :

Type(s)

postcallfunction

postcallfunction :

Type(s)

postcalldata

postcalldata :

Type(s)