README

This is the official Laravel client library for the Mailify service API, which allows you to send emails.

Mailify::send('welcome_template')->to('yoyo.elimah@gmail.com')->now();

Installation

You can install the package via composer:

composer require axazara/mailify-laravel

php artisan mailify:install

You must publish the config file with:

php artisan mailify:install

This is the contents of the published config file:

return [
    'api_key'  => env('MAILIFY_API_KEY', 'default'),
    'reply_to' => env('MAILIFY_REPLY_TO'),
    'priority' => env('MAILIFY_PRIORITY', 0),
    'queue'    => env('MAILIFY_QUEUE', 'default'),
    'env'      => env('MAILIFY_ENV', 'live'),
    'api_url'  => env('MAILIFY_API_URL'),
];

Setup

To use Mailify, you muste set your API key in the config file or in the .env file.

MAILIFY_API_KEY=YOUR_API_KEY // Your Mailify API key

IMPORTANT

Save your API key as an environment variable in your .env file. Do not hardcode it in your code.

You must not share your API key with anyone.

You must not commit your API key to version control.

Templates

To use Mailify, you must define your templates in Mailify config file. Mailify config file has a templates key which is an array of templates. This array is for storing the templates. The key is the name of the template and the value is the id of the template. Example:

'templates' => [    
    'template_name' => 'template_id',
    'welcome_template' => 'welcome_template_id',
    'reset_password_template' => 'reset_password_template_id',
],

You can use the template name in the Mailify::send() method.

Example:

 Mailify::send('template_name')->to('you@smile.com')->now();

IMPORTANT

The template id must be a valid template id from your Mailify dashboard.

Usage

To send an Email, simply use the following syntax:

Mailify::send('template_name')->to('john@getmailify.com')->now();

send() is take the Mailify template name
to() is take the recipient email address
now() if you want to send the email immediately

You can also pass another parameter though the below method :

Note: All parameters must be passed before the now() or later() method.

- Template parameters : (optional)

This is an array of parameters that will be passed to the template. The parameters will be available in the template as variables.

 ->with([
    'name' => 'John Doe',
    'order_id' => 1234,
])

- Reply to : (optional)

The reply to address is the address that will be used when the recipient replies to the email. If not specified, the replyTo address will be the address specified in the Mailify dashboard. You can also set default replyTo address in the config file or use MAILIFY_REPLY_TO environment variable in .env file.

 ->replyTo('team@exemple.com')

- Priority : (optional)

The priority of email. Mailify supports 2 priority level : 0 (default) and 1 (high); You can also set default priority in the config file or use the MAILIFY_PRIORITY environment variable in .env file. Default priority is 0.

 ->priority(1)

Example Usage with full parameters

Mailify::send('template_name')
    ->to('john@example.com')
    ->with([
        'name' => 'John Doe',
        'order_id' => 1234,
    ])
    ->replyTo('help@company.com')
    ->priority(1)
    ->now();

Sending an email later

You may also choose to queue the email sending with later() or afterResponse() method.

later() method is send the email via queue Mailify use the Laravel queue system to send email though default queue. This is useful if you don't want to wait for the email to be sent before returning a response to the user or if you want to send the email in the background.
Note:
- You must have a queue worker running in order to send the email. You can read more about queue workers in the Laravel documentation.
- If you want to use a custom queue, you need to set the MAILIFY_QUEUE environment variable to the name of the queue you wish to use. Be sure to have a queue worker running to process the queued messages, otherwise they will not be sent.
afterResponse() method is used to send email after the response is sent to the browser. This method do not require queue driver to be configured.

Note: This method only work if your web server is using FastCGI or run with Laravel Octane (Swoole, RoadRunner).

Local Development

If you are using Mailify in a local development environment, you don't want to send real emails. Instead, you can use the Mailify with Mailtrap SMTP integration to view emails in your browser instead of sending them.

To avoid error in local development or testing environment you can set the MAILIFY_ENV environment variable to test in your .env file, this will prevent package to send email to Mailify API. ⚠️Be sure to set the MAILIFY_ENV environment variable to live when deploying to production.

MAILIFY_ENV=test

Error & Exceptions

If an error occurs while sending the email, an exception will be thrown. You can catch the exception and handle it accordingly.

try {
    Mailify::send('template_name')->to('test@test.com')->now();
} catch (Exception $exception) {
    // Handle the exception
}

Possible exceptions are :

Axazara\Mailify\Exceptions\ApiKeyIsMissing
Axazara\Mailify\Exceptions\PriorityIsInvalid
Axazara\Mailify\Exceptions\ReplyToIsInvalid
Axazara\Mailify\Exceptions\SendingError
Axazara\Mailify\Exceptions\ToIsInvalid

All error is logged in the laravel.log file, you can find the log file in the storage/logs directory. Exceptions is thrown only if the APP_DEBUG environment variable is set to true.

Helpful links

Read the Mailify documentation to learn more about Mailify.
Read the Laravel documentation to learn more about Laravel.
Read the Laravel Queue documentation to learn more about Laravel Queue.
Read the Laravel Octane documentation to learn more about Laravel Octane.
Read the Mailtrap documentation to learn more about Mailtrap.

Next features (TODO) :

[ ] Add ->attach() method to attach file to email
[ ] Add ->bcc() method to send email to BCC
[ ] Add ->cc() method to send email to CC
[ ] Add ->from() method to set email sender
[ ] Add ->delay() method to delay mail sending to specified timestamp

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

If you've found a bug regarding security please mail hello@axazara.com instead of using the issue tracker..

Credits

License

The MIT License (MIT). Please see License File for more information.

axazara / mailify-laravel

Maintainers

Details