Arguments

$args

Array Mail values (to, subject, body...)

Sending mail

NOTE! Although Mail -allows you to define any sender (from) you want, mail is commonly sent via IMAP mailbox, which requires sender to the same ase mailbox address (defined in mailbox config).

Basic use

Send an email to a given address:

$this->get('mail', Array(
  'to'      => 'your@mail.com',
  'subject' => 'Mail title',
  'body'    => 'Mail message'
))->send();

You can also use set -methods:

$this->get('mail')
  ->setTo('your@mail.com')
  ->setSubject('Mail title')
  ->setBody('Mail message')
  ->send();

Setting values from page

You can set the mail's addresses by giving the corresponding field -object:

$this->get('mail', Array(
  'to' => $Order->client->email,
  'subject' => 'Our offer',
  'body' => 'You got our offer, didn't you?'
))->send();

Setting attachments

You can add attachments with the attachment() method:

$this->get('mail', Array(
  'to' => $Order->client->email,
  'subject' => 'Here is our order',
  'attachment' => $Order->order_attachment->file
))->send();

Or by giving filename and data:

$Mail->attachment('MyFilename.txt',$fileContent);

Setting values

Setting multiple addresses

All value adding methods (to(), setTo() addTo()) can have multiple arguments. These examples will add addresses from both variables.

$Mail = $this->get('mail');
$Mail->setTo( $customerMail , $sellerMail );
$Mail->addTo( $customerMail , $sellerMail );

Address field arguments are interpreted through an address validator -method. Addresses can be set in array or space/comma/semicolon/colon -separated string. Different input forms come in handy if addresses are already in one of those formats.

All examples below add two addresses into the 'to' -field:

$Mail = $this->get('mail');
$Mail->addTo('customer@mail.com','seller@mail.com');
$Mail->addTo('customer@mail.com seller@mail.com');
$Mail->addTo('customer@mail.com,seller@mail.com');
$Mail->addTo('customer@mail.com:seller@mail.com');
$Mail->addTo('customer@mail.com;seller@mail.com');
$Mail->addTo(Array('customer@mail.com','seller@mail.com'));

Values can be added the same way also for the subject, footer, body and file -fields.

$Mail = $this->get('mail')
  ->setSubject('Subject base','Additional information');
---
Subject will be: 'Subject base Additional information'

Multiple values will be combined using the field's delimiter. Default delimiter can be changed with set{name}Delimiter() -method.

$Mail = $this->get('mail');
$Mail->setSubjectDelimiter(': ');
$Mail->setSubject('Subject base','Additional information');
---
Subject will be: 'Subject base: Additional information'

Defining optional addresses

setTo() will clear the old values and add new ones, IF given argument(s) has at least one valid address. If it doesn't, the old value will be conserved.

$Mail = $this->get('mail')
  ->setTo( $validMail , $validMail2 )
  ->setTo( $invalidMail );
---
Will send to: $validMail, $validMail2
Because $invalidMail is ignored.

$Mail = $this->get('mail')
  ->setTo( $validMail )
  ->setTo( $validMail2 );
---
Will send to: $validMail2
Because $validMail is overwritten by $validMail2.

$Mail = $this->get('mail')
  ->setTo( $validMail )
  ->setTo( $invalidMail , $validMail2 );
---
Will send to: $validMail2
Because second to() has a valid address in $validMail2 and $validMail is overwritten.

$Mail = $this->get('mail')
  ->setTo( $validMail , $validMail2 )
  ->setTo( $validMail3 );
---
Will send to: $validMail3
Because $validMail and $validMail2 are overwritten by $validMail3.

$Mail = $this->get('mail')
  ->setTo( $validMail )
  ->setTo( $validMail2 , $validMail3 );
---
Will send to: $validMail2 , $validMail3
Because $validMail is overwritten by $validMail2 and $validMail3

Same overwriting rules apply also to the subject, footer, body and file -fields. In this example 'Default subject' is used as subject if $mySubject has no valid value (empty string or undefined value). ie. $mySubject is ignored and therefore 'Default subject' is conserved.

$Mail = $this->get('mail')
  ->setSubject( 'Default subject' )
  ->setSubject( $emptySubject );
---
subject is: 'Default subject'

$Mail = $this->get('mail')
  ->setSubject( 'Default subject' )
  ->setSubject( 'Other subject' );
---
subject is: 'Other subject'

Triggers

You can bind listener functions to Mail using bind -method:

$Mail->bind('send.error', function($event,$Mail){
    print "ERROR SENDIN MAIL TO ".$MAil->getTo()." ".$Mail-getError();
});

Mailer

Default mailer is defined in system ini.php and it can be overridden in account config.php or account preferences yaml. You can also set the Mailer and parameters for single Mail -object:

$this->get('mail', Array(
  'from'    => 'my@mail.com',
  'to'      => 'your@mail.com',
  'subject' => 'Mail title',
  'body'    => 'Mail message'
))->setMailer('PhpMailer')->send();

You can also get the Mailer object and handle it directly:

// Create mail
$Mail = $this->get('mail', Array(
  'subject' => 'Mail title',
  'body'    => 'Mail message'
));

// Get Mailer -object.
$Mailer = $Mail->getMailer();

// Get object that Mailer uses to send emails.
$PhpMailer = $Mailer->getSender();

// Add address directly to PhpMailer
$PhpMailer->AddAddress($email,$personName);

// Send mail
$Mail->send();

// Get error from PhpMailer object
$error = $PhpMailer->ErrorInfo;

Smtp

Send mail using Smtp mailbox:

// Create mail
$Mail = $this->get('mail', Array(
    'to'      => 'your@mail.com',
    'subject' => 'Mail title',
    'body'    => 'Mail message'
));

// Set mailer
$Mail->setMailer('Smtp',Array(
    'Host' => 'mail.mydomain.com',
    'Username' => 'user',
    'Password' => 'passwd',
    'SaveCopyTo' => 'Sent Mail' // Folder name
));

// Send mail using the given mailbox parameters
$Mail->send();

Methods

Common methods

Method	Return value	Description
type(val)	this	Sets content type: HTML | Text (default)
bind(name, fn(event,$Mail) )	this	Bind listener function to given event.
trigger(name)	this	Manually trigger listeners in given event.
send()	bool	Sends the mail. Return TRUE if message was sent.
isSuccess()	bool	Return true if message was sent.
getError()	string	Get mailer error message.

Static functions

Method	Return value	Description
eMail::getMailAddresses(val)	array	Extracts all valid email addresses from given argument. Argument can be array(val,val) or string: 'val,val', 'val:val', 'val:val' or 'val val'
eMail::sendMail($mail)	bool	Static use. Use only if $mad is not set!!

Trigger Events

Name	Description
send.start	Triggered when send -function is executed.
send.error	Triggered when there was an error sending the mail.
send.success	Triggered when mail was succesfully sent.
send.ready	Triggered after send() -function is finished (success or not)

Field methods

All fields have methods that function in the same way. (Replace the 'Fieldname' with the field that you want to handle). Methods that return 'this' are chainable.

Method	Return value	Description
setData(array)	this	Set to, from etc. values from associative array.
fieldname(val)	this	-> setFieldname(val)
fieldname()	array	-> getFieldname()
getFieldname()	array	Get values in array.
setFieldname(val)	this	Clears value and sets new value(s), IF valid value is given.
addFieldname(val)	this	Adds valid value(s).
clearFieldname()	this	Clears all values in field.
hasFieldname()	bool	Return true if field has a value.
countFieldname()	int	Return number of values set to field.
setFieldnameDelimiter()	this	Set a delimiter used to combine two or more arguments.

Field names

Field	Type	Delimiter	Description
from	address	comma	Senders email. Only last valid address is used.
to	address	comma	Receivers emails(s).
cc	address	comma	Send copy to email(s).
bcc	address	comma	Send hidden copy to emails(s).
subject	string	space	Message subject.
body	string	newline*2	Message title.
footer	string	newline	Text to be added after the body.
attachment	file		File to be included as attachment.

Alternative field names

The class supports alternative field names (for semantic and language reasons). It makes no difference whether you use the original or the alternative name. ie. $mail->setFrom( $address ) is same as writing $mail->setSender( $address ).

Field	Optional names	Finnish equivalents
from	sender	lahettaja
to	receiver	vastaanottaja
cc	copy	kopio
bcc	blindcopy	piilokopio
subject	title	otsikko, aihe
body	message, content, text	viesti
footer		allekirjoitus
attachment	file	liite, tiedosto

Mailer

Available mailers: PhpMailer, Smtp, Mimemail (deprecated)

Method	Return value	Description
setMailer($name,$param)	this	Set mailer class and parameters.
setMailerParameters($param)	this	Set mailer parameters.
getMailer()	this	Get mailer object.
getMailerName()	string	Get mailer class name.
getMailerParameters()	this	Get current mailer parameters.
isSuccess()	bool	Return true, mail was sent.
getError()	string	Error text, if error in sending.