A Mailgun package for Laravel 4 for sending emails using the Mailgun HTTP API. It's main advantage is that the syntax is the same as the Laravel Mail component and I also tried to give it very simmilar functionality. So if you've used that component before, using the Mailgun package should be a breeze.
This package makes use of the Mailgun-PHP library, version 1.7.
[](https://packagist.org/packages/bogardo/mailgun) [](https://packagist.org/packages/bogardo/mailgun)
](https://packagist.org/packages/bogardo/mailgun){kind=link}
](https://packagist.org/packages/bogardo/mailgun){kind=link}
Open your composer.json file and add the following to the require key:
"bogardo/mailgun": "dev-master"
All issues with compatibility for Laravel 4.1 and 4.0 have been resolved. You can still use one of the two tagged versions if you'd like.
After adding the key, run composer update from the command line to install the package
composer updateAdd the service provider to the providers array in your app/config/app.php file.
'Bogardo\Mailgun\MailgunServiceProvider'
Before you can start using the package we need to set some configurations.
To do so you must first publish the config file, you can do this with the following artisan command.
php artisan config:publish bogardo/mailgunAfter the config file has been published you can find it at: app/config/packages/bogardo/mailgun/config.php
In it you must specify the from details, your Mailgun api key and the Mailgun domain.
The Mailgun package offers most of the functionality as the Laravel 4 Mail component.
The Mailgun::send method may be used to send an e-mail message:
Mailgun::send('emails.welcome', $data, function($message)
{
$message->to('[email protected]', 'John Smith')->subject('Welcome!');
});The first argument passed to the send method is the name of the view that should be used as the e-mail body.
Mailgun supports 2 types of bodies: text and html.
You can specify the type of body like so:
Mailgun::send(array('html' => 'html.view', 'text' => 'text.view'), $data, $callback);If you have a html body as well as a text body then you don't need to specify the type, you can just pass an array where the first item is the html view and the second item the text view.
Mailgun::send(array('html.view','text.view'), $data, $callback);When you only want to send an html body you can just pass a string.
Mailgun::send(array('html.view'), $data, $callback);When only sending a text body, just must pass an array and specify the type.
Mailgun::send(array('text' => 'text.view'), $data, $callback);The second argument passed to the send method is the $data array that is passed to the view.
Note: A
$messagevariable is always passed to e-mail views, and allows the inline embedding of attachments. So, it is best to avoid passing a (custom)messagevariable in your view payload.
You can access the values from the $data array as variables using the array key.
Example:
$data = array(
'customer' => 'John Smith',
'url' => 'http://laravel.com'
);
Mailgun::send('emails.welcome', $data, function($message)
{
$message->to('[email protected]', 'John Smith')->subject('Welcome!');
});View emails.welcome:
<body>
Hi {{ $customer }},
Please visit {{ $url }}
</body>Renders to:
<body>
Hi John Doe,
Please visit http://laravel.com
</body>You can specify the mail options within the closure.
The recipient methods all accept two arguments: email and name where the name field is optional.
The to method
Mailgun::send('emails.welcome', $data, function($message)
{
$message->to('[email protected]', 'Recipient Name');
});The cc method
Mailgun::send('emails.welcome', $data, function($message)
{
$message->cc('[email protected]', 'Recipient Name');
});The bcc method
Mailgun::send('emails.welcome', $data, function($message)
{
$message->bcc('[email protected]', 'Recipient Name');
});To send an email to multiple recipients you can also pass an array as the first parameter to the to, cc and/or bcc methods.
Mailgun::send('emails.welcome', $data, function($message)
{
$message->to(array(
'[email protected]',
'[email protected]'
));
});The array should only contain strings with the email address.
If you still want to be able to set the recipient name there are two options:
- Call the
tomethod multiple times:
Mailgun::send('emails.welcome', $data, function($message) use ($users)
{
foreach ($users as $user) {
$message->to($user->email, $user->name);
}
});- Give the strings in the
arraythe correct format for including names:'name' <email>
array(
"'Mr. Bar' <[email protected]>",
"'Ms. Foo' <[email protected]>"
);Note: Mailgun limits the number of recipients per message to 1000
In the Mailgun config file you have specified the from address. If you would like, you can override this using the from method. It accepts two arguments: email and name where the name field is optional.
#with name
$message->from('[email protected]', 'Recipient Name');
#without name
$message->from('[email protected]');Setting the email subject
Mailgun::send('emails.welcome', $data, function($message)
{
$message->subject('Email subject');
});Setting a reply-to address
Mailgun::send('emails.welcome', $data, function($message)
{
$message->replyTo('[email protected]', 'Helpdesk');
});If the reply_to config setting is set, the reply-to will be automatically set for all messages You can overwrite this value by adding it to the message as displayed in the example.
To add an attachment to the email you can use the attach method. You can add multiple attachments.
Since mailgun-php 1.6, the ability to rename attachments has been added due to the upgrade to guzzle 1.8
It accepts 2 arguments:
- $path | The path to the image
- $name (optional) | The remote name of the file (attachment is renamed server side)
Mailgun::send('emails.welcome', $data, function($message)
{
$message->attach($pathToFile);
});> The to, cc, bcc, sender, from, subject etc... methods are all chainable: > ```php > $message > ->to('[email protected]', 'Recipient Name') > ->cc('[email protected]', 'Recipient Name') > ->subject('Email subject'); > ```
Embedding inline images into your e-mails is very easy.
In your view you can use the embed method and pass it the path to the file. This will return a CID (Content-ID) which will be used as the source for the image. You can add multiple inline images to your message.
Since mailgun-php 1.6, the ability to rename attachments has been added due to the upgrade to guzzle 1.8
The embed method accepts 2 arguments:
- $path | The path to the image
- $name (optional) | The remote name of the file (attachment is renamed server side)
<body>
<img src="{{ $message->embed($pathToFile) }}">
</body>$data = array(
'img' => 'assets/img/example.png',
'otherImg' => 'assets/img/foobar.jpg'
);
Mailgun::send('emails.welcome', $data, function($message)
{
$message->to('[email protected]', 'Recipient Name');
});<body>
<img src="{{ $message->embed($img) }}">
<img src="{{ $message->embed($otherImg, 'custom_name.jpg') }}">
</body><body>
<img src="cid:example.png">
<img src="cid:custom_name.jpg">
</body>The $message variable is always passed to e-mail views by the Mailgun class.
Mailgun provides the ability to set a delivery time for emails up to 3 days in the future.
To do this you can make use of the later method.
While messages are not guaranteed to arrive at exactly at the requested time due to the dynamic nature of the queue, Mailgun will do it's best.
The later method works the same as the (default) send method but it accepts 1 extra argument.
The extra argument is the amount of seconds (minutes, hours or days) from now the message should be send.
If the specified time exceeds the 3 day limit it will set the delivery time to the maximum of 3 days.
To send an email in 10 seconds from now you can do the following:
Mailgun::later(10, 'emails.welcome', $data, function($message)
{
$message->to('[email protected]', 'John Smith')->subject('Welcome!');
});When passing a string or integer as the first argument, it will interpret it as seconds. You can also specify the time in minutes, hours or days by passing an array where the key is the type and the value is the amount.
For example, sending in 5 hours from now:
Mailgun::later(array('hours' => 5), 'emails.welcome', $data, function($message)
{
$message->to('[email protected]', 'John Smith')->subject('Welcome!');
});When scheduling messages, make sure you've set the correct timezone in your
app/config/app.phpfile.
Sometimes it’s helpful to categorize your outgoing email traffic based on some criteria, perhaps for separate signup emails, password recovery emails or for user comments. Mailgun lets you tag each outgoing message with a custom tag. When you access the Tracking page within the Mailgun control panel, they will be aggregated by these tags.
Warning: A single message may be marked with up to 3 tags. Maximum tag name length is 128 characters. Mailgun allows you to have only limited amount of tags. You can have a total of 4000 unique tags.
To add a Tag to your email you can use the tag method.
You can add a single tag to an email by providing a string.
Mailgun::send('emails.welcome', $data, function($message)
{
$message->tag('myTag');
});To add multiple tags to an email you can pass an array of tags. (Max 3)
Mailgun::send('emails.welcome', $data, function($message)
{
$message->tag(array('Tag1', 'Tag2', 'Tag3'));
});If you pass more than 3 tags to the
tagmethod it will only use the first 3, the others will be ignored.
[](https://bitdeli.com/free "Bitdeli Badge")
](https://bitdeli.com/free){kind=link}