AkActionMailer

AkActionMailer allows you to send email from your application using a mailer model and views.

Mailer Models

To use AkActionMailer, you need to create a mailer model.

$ ./script/generate mailer Notifier signupNotification

The generated model inherits from AkActionMailer. Emails are defined by creating methods within the model which are then used to set variables to be used in the mail template, to change options on the mail, or to add attachments.

Examples

class Notifier extends AkActionMailer
{
  public function signupNotification($Recipient)
  {
    $this->setRecipients($Recipient->getEmailAddressWithName());
    $this->setFrom("system@example.com");
    $this->setSubject("New account information");
    $this->setBody(array('account' => $Recipient ));
  }
}

Mailer methods have the following configuration methods available.

setRecipients Takes one or more email addresses. These addresses are where your email will be delivered to. Sets the To: header.

setSubject The subject of your email. Sets the Subject: header.

setFrom Who the email you are sending is from. Sets the From: header.

setCc Takes one or more email addresses. These addresses will receive a carbon copy of your email. Sets the Cc: header.

setBcc Takes one or more email address. These addresses will receive a blind carbon copy of your email. Sets the Bcc header.

setSentOn The date on which the message was sent. If not set, the header wil be set by the delivery agent.

setContentType Specify the content type of the message. Defaults to text/plain.

setHeaders Specify additional headers to be set for the message, e.g. $this→setHeaders(array('X-Mail-Count' ⇒ 107370));.

setBody - This method has special behavior. It takes an array which generates an instance variable named after each key in the array containing the value that that key points to.

So, for example, setBody(array(“account” ⇒ $Recipient)); would result in an instance variable $account with the value of $Recipient being accessible in the view.

Mailer views

Like AkAkActionController, each mailer class has a corresponding view directory in which each method of the class looks for a template with its name. To define a template to be used with a mailing, create an .tpl file with the same name as the method in your mailer model. For example, in the mailer defined above, the template at app/views/notifier/signup_notification.tpl would be used to generate the email.

Variables defined in the model are accessible as instance variables in the view.

Emails by default are sent in plain text, so a sample view for our model example might look like this:

Hi {account.name},
Thanks for joining our service! Please check back often.

You can even use Action View helpers in these views. For example:

You got a new note!
<?=$text_helper->truncate($note->body, 25);?>

Mailer layouts

Similar to the layouts for Controller/action views you can define layouts for your mailers. Each mailer can provide layouts based on the content-type.

For example, if the following templates exist:

layout.text.plain.tpl
layout.text.html.tpl

they will be used as the layout for the text/plain and text/html part of the message.

As in normal views you define the layout:

<html>
  <body>
    <h2>{Title}</h2>
    
    <!-- content body comes here -->
      {content_for_layout?}
    <!-- end content -->
    
    <p class="footer">
      {footer_message?}
    </p>
  </body>
</html>

Generating URLs for mailer views

If your view includes URLs from the application, you need to use Ak::urlFor in the mailing method instead of the view. Unlike controllers from Action View, the mailer instance doesn't have any context about the incoming request. That's why you need to jump this little hoop and supply all the details needed for the URL.

Example

function signupNotification($Recipient)
{
    // This is the same as calling each individual setter
    $this->setAttributes(array(
        'recipients' => $Recipient->getEmailAddressWithName(),
        'from'       => "system@example.com",
        'subject'    => "New account information",
        'body'       => array(
            'account'   => $Recipient,
            'home_page' => Ak::urlFor(array('host' => "example.com", 'controller' => "welcome", 'action' => "greeting"))
        )
    ));
}

You can now access @home_page in the template and get http://example.com/welcome/greeting.

Sending mail

Once a mailer action and template are defined, you can deliver your message or create it and save it for delivery later:

Sends the email

  Notifier::deliver('signup_notification', $David);

A PEAR::Mail object

  $Message = Notifier::create('signup_notification', $David);

  Notifier::deliver($Message);

You never instantiate your mailer class. Rather, your delivery instance methods are automatically wrapped in class methods that are called statically

The signup_notification method defined above is delivered by invoking

$Notifier = new Notifier(); $Notifier->signupNotification(); $Notifier->deliver();

HTML email

To send mail as HTML, make sure your view (the .tpl file) generates HTML and set the content type to html.

class ApplicationMailer extends AkActionMailer
{
    public function signupNotification($Recipient)
    {
        $this->setAttributes(array(
            'recipients' => $Recipient->getEmailAddressWithName(),
            'from'       => "system@example.com",
            'subject'    => "New account information",
            'body'       => array('account'   => $Recipient),
            'content_type' => text/html" //    Here's where the magic happens
        ));
    }
}

Multipart email

You can explicitly specify multipart messages:

class ApplicationMailer extends AkActionMailer
{
    public function signupNotification($Recipient)
    {
        $this->setAttributes(array(
            'recipients' => $Recipient->getEmailAddressWithName(),
            'from'       => "system@example.com",
            'subject'    => "New account information"
        ));
        
        $this->addPart(array(
            'content_type' => "text/html",
            'body' => $this->renderMessage('signup-as-html', 'account' => $recipient)));
        
        $this->addPart("text/plain", array(
            'transfer_encoding' = "base64",
            'body' => $this->renderMessage('signup-as-plain', 'account' => $recipient)));
    }
}

Multipart messages can also be used implicitly because AkActionMailer will automatically detect and use multipart templates, where each template is named after the name of the action, followed by the content type. Each such detected template will be added as separate part to the message.

For example, if the following templates existed: signup_notification.text.plain.tpl signup_notification.text.html.tpl

Each would be rendered and added as a separate part to the message, with the corresponding content type. The same body array is passed to each template.

Attachments

Attachments can be added by using the +addAttachment+ method.

Example

class ApplicationMailer extends AkActionMailer
{
    // attachments
    public function signupNotification($Recipient)
    {
        $this->setAttributes(array(
            'recipients' => $Recipient->getEmailAddressWithName(),
            'from'       => "system@example.com",
            'subject'    => "New account information"
        ));
        
        $this->addAttachment(array(
            'content_type' => 'image/jpeg',
            'body' => Ak::file_get_contents("an-image.jpg")));
        
        $this->addAttachment('application/pdf', generate_your_pdf_here());
    }
}

Configuration options

These options are specified on the class level, as class attriibutes $AkActionMailerInstance→templateRoot = ”/my/templates”;

templateRoot - template root determines the base from which template references will be made.

server_settings

Allows detailed configuration of the server:

address Allows you to use a remote mail server. Just change it from its default “localhost” setting.

port On the off chance that your mail server doesn't run on port 25, you can change it.

domain If you need to specify a HELO domain, you can do it here.

user_name If your mail server requires authentication, set the username in this setting.

password If your mail server requires authentication, set the password in this setting.

authentication If your mail server requires authentication, you need to specify the authentication type here. Options are: plain, login, cram_md5

delivery_method Defines a delivery method. Possible values are 'php' (default), 'smtp', and 'test'.

perform_deliveries Determines whether AkActionMailer::deliver(*) methods are actually carried out. By default they are, but this can be turned off to help functional testing.

deliveries Keeps an array of all the emails sent out through the Action Mailer with delivery_method 'test'. Most useful for unit and functional testing.

default_charset The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also pick a different charset from inside a method with $this→charset.

default_content_type The default content type used for the main part of the message. Defaults to “text/plain”. You can also pick a different content type from inside a method with $this→content_type.

default_mime_version The default mime version used for the message. Defaults to “1.0”. You can also pick a different value from inside a method with $this→mime_version.

default_implicit_parts_order When a message is built implicitly (i.e. multiple parts are assembled from templates which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to array(“multipart/alternative”, “text/html”, “text/enriched”, “text/plain”). Items that appear first in the array have higher priority in the mail client and appear last in the mime encoded message. You can also pick a different order from inside a method with $this→implicit_parts_order

Ak Action Mailer