Download the PHP package hydreflab/laravel-mailer without Composer

Laravel Mailer

Wrapper with unified interface for sending emails with Mandrill or SendGrid with use of templates mechanism.

Overview

This package provides wrapper for both Mandrill and SendGrid email sending engines and utilizes possibility to send emails with use of already prepared templates.

For more info, please check:

• https://mandrill.zendesk.com/hc/en-us/articles/205582507-Getting-Started-with-Templates (for Mandrill)
• https://sendgrid.com/docs/API_Reference/Web_API_v3/Transactional_Templates/index.html (for SendGrid)

Both mailers have unified interface, so changing your email sending engine is pretty painless.

Package also adds possibility to configure your Mandrill templates in the code and then seed them into your Mandrill account. Possibility to seed templates into SendGrid is work in progress.

Compatibility

Package is compatible with Laravel 5.2.

SendGrid

New SendGrid API has some downsides when it comes to sending emails to multiple recipients. In order not to break anything, SendGrid mailer treats all recipients as of to type.

For more information, please check https://github.com/sendgrid/sendgrid-php#please-read-this.

Installation

Version >= 2.0

1. Add hydreflab/laravel-mailer to your composer.json:

   • If you will be using Mandrill, add weblee/mandrill to your composer.json:

   • If you will be using SendGrid, add sendgrid/sendgrid to your composer.json:
2. Add DeSmart\Mailer\MailerServiceProvider::class to your config/app.php file.
3. Publish mailer configuration: php artisan vendor:publish. This will create config/mailer.php file.

4. Mailer configuration is based on .env entries:

5. (Mandrill usage only) If you want to use templates create/update functionality:
   1. Add DeSmart\Mailer\Mandrill\MandrillTemplatesSeedCommandServiceProvider::class to your config/app.php file.
   2. Publish Mandrill templates configuration: php artisan vendor:publish. This will create config/mandrill-templates.php file where you can configure your Mandrill templates. This configuration is used by mandrill_templates:seed artisan command.
   3. Important Step 5.i & 5.ii should be done after installing Mailer package - this is because template seeder uses mailer configuration which has to be published first.

Version < 2.0

Package implements wrapper only for Mandrill.

If possible, please use version >= 2.0

1. Add hydreflab/laravel-mailer to your composer.json:

2. Add DeSmart\Mailer\ServiceProvider\MandrillServiceProvider::class to your config/app.php file.
3. Publish Mandrill templates configuration: php artisan vendor:publish. This will create config/mandrill-templates.php file where you can configure your templates. This configuration is used by mandrill_templates:seed artisan command.

4. Mandrill mailer uses configuration for default sender email and name. You can find it inside config/mail.php file:

5. Set up proper API key in your .env file:

Interface overview

Package provides unified interface for both mailers:

• setFromEmail(): overrides default email sender; takes string argument
• setFromName(): overrides default email sender name; takes string argument
• setSubject(): sets email subject; takes string argument
• setTemplate(): sets template identifier; takes string argument
• addRecipient(): adds recipient to the message; requires Recipient object as argument
• addHeader(): adds proper SMTP header to the message; requires Header object as argument
• setReplyTo(): sets reply-to email; takes string argument
• addGlobalVariable(): adds variable shared by all recipients (in Mandrill it is equivalent to global merge var, in SendGrid it is equivalent to section); requires Variable object as argument
• addLocalVariable(): adds variable for specified recipient (in Manrdill it is equivalent to merge var, in SendGrid it is equivalent to substitution); requires Recipient and Variable objects as arguments
• addAttachment(): adds attachment to the message; requires Attachment object as argument
• send(): sends message to previously defined recipients; email subject (string) and template identifier (string) can be passed (if subject and/or template id was not set before)
• queue(): adds email to queue (it uses Laravel queue mechanism); queue name (string) must be passed as first param; email subject (string) and template identifier (string) can also be passed (if not set before)
• getData(): gets mailer whole configuration, i.e. recipients, variables, header, etc.; returns array
• setData(): sets mailer configuration; requires array

Recipient object

Recipient object describes details of recipient.

Recipient object takes three arguments:

• recipient name: string
• recipient email: string
• recipient type (optional): RecipientType object (if recipient type is not passed, type is set as to)

RecipientType object

RecipientType object describes type of recipient - is he either:

• primary recipient (to) or
• should be in copy (cc) or
• should be in hidden copy (bcc).

RecipientType object is simple value object with named constructors:

• RecipientType::to()
• RecipientType::bcc()
• RecipientType::cc()

Variable object

Variable object describes details of variable that is used for personalizing email content. Variable (defined by its name) is placed in email templates.

Variable object takes two arguments:

• variable name: string
• variable value: string

Header object

Header object described SMTP header details. for more details about acceptable headers, check Mandrill/SendGrid API docs.

Header object takes two arguments:

• variable name: string
• variable value: string

Attachment object

Attachment object contains data about file attached to the message. Content set in object should be in plain text.

For Mandrill, content is base64 encoded when passed to API.

For SendGrid, temporary file with content is created, then path to this file is passed to API. After message is sent, temporary file is deleted.

Attachment object takes three arguments:

• attachment MIME type: string
• attachment filename: string
• attachment content (in plain text): string

Usage

PHP

Mandrill templates

In order to configure your templates, edit config/mandrill-templates.php file:

When your configuration is ready, you can run php artisan mandrill_templates:seed command to create and/or update Mandrill templates.