MailerSend PHP SDK
Table of Contents
- Installation
- Usage
- Sending and email
- Sending and email with CC and BCC
- Sending an email with variables (simple personalisation)
- Sending an email with personalization (advanced personalisation)
- Sending a template-based email
- Sending an email with attachment
- Debugging validation errors
- Activity API
- Analytics API
- Domains API
- Messages API
- Recipients API
- Tokens API
- Webhooks API
- Testing
- Support and Feedback
- License
Installation
Requirements
- PHP 7.4
- PSR-7 and PSR-18 based HTTP adapter
- An API Key from mailersend.com
Setup
This library is built atop of PSR-7 and PSR-18. You will need to install some implementations for those interfaces.
composer require php-http/guzzle7-adapter nyholm/psr7
After that you can install the SDK.
composer require mailersend/mailersend
Usage
Sending a basic email.
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('[email protected]', 'Your Client'),
];
$emailParams = (new EmailParams())
->setFrom('[email protected]')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject')
->setHtml('This is the HTML content')
->setText('This is the text content');
$mailersend->email->send($emailParams);
Sending an email with CC and BCC
Send an email with CC and BCC.
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('[email protected]', 'Your Client'),
];
$cc = [
new Recipient('[email protected]', 'CC'),
];
$bcc = [
new Recipient('[email protected]', 'BCC'),
];
$emailParams = (new EmailParams())
->setFrom('[email protected]')
->setFromName('Your Name')
->setRecipients($recipients)
->setCc($cc)
->setBcc($bcc)
->setSubject('Subject')
->setHtml('This is the HTML content')
->setText('This is the text content');
$mailersend->email->send($emailParams);
Sending an email with variables (simple personalization)
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Variable;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('[email protected]', 'Your Client'),
];
$variables = [
new Variable('[email protected]', ['var' => 'value'])
];
$emailParams = (new EmailParams())
->setFrom('[email protected]')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject {$var}')
->setHtml('This is the html version with a {$var}.')
->setText('This is the text versions with a {$var}.')
->setVariables($variables);
$mailersend->email->send($emailParams);
Sending an email with personalization (advanced personalization)
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Personalization;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('[email protected]', 'Your Client'),
];
$personalization = [
new Personalization('[email protected]', [
'var' => 'variable',
'number' => 123,
'object' => [
'key' => 'object-value'
],
'objectCollection' => [
[
'name' => 'John'
],
[
'name' => 'Patrick'
]
],
])
];
$emailParams = (new EmailParams())
->setFrom('[email protected]')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject {$var}')
->setHtml('This is the html version with a {$var}.')
->setText('This is the text versions with a {$var}.')
->setPersonalization($personalization);
$mailersend->email->send($emailParams);
Sending a template-based email
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Variable;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('[email protected]', 'Your Client'),
];
$variables = [
new Variable('[email protected]', ['var' => 'value'])
];
$tags = ['tag'];
$emailParams = (new EmailParams())
->setFrom('[email protected]')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject')
->setTemplateId('ss243wdasd')
->setVariables($variables);
$mailersend->email->send($emailParams);
Sending an email with attachment
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Attachment;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('[email protected]', 'Your Client'),
];
$attachments = [
new Attachment(file_get_contents('attachment.jpg'), 'attachment.jpg')
];
$emailParams = (new EmailParams())
->setFrom('[email protected]')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject')
->setHtml('This is the html version.')
->setText('This is the text version.')
->setAttachments($attachments);
$mailersend->email->send($emailParams);
Debugging validation errors
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Variable;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
use MailerSend\Exceptions\MailerSendValidationException;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('[email protected]', 'Your Client'),
];
// This should be [email protected], as in $recipients
$variables = [
new Variable('[email protected]', ['var' => 'value'])
];
$emailParams = (new EmailParams())
->setFrom('[email protected]')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject {$var}')
->setHtml('This is the html version with a {$var}.')
->setText('This is the text versions with a {$var}.')
->setVariables($variables);
try{
$mailersend->email->send($emailParams);
} catch(MailerSendValidationException $e){
// See src/Exceptions/MailerSendValidationException.php for more more info
print_r($e->getResponse()->getBody()->getContents());
}
Activity
List activities
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\ActivityParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$activityParams = (new ActivityParams())
->setPage(3)
->setLimit(15)
->setDateFrom(1623073576)
->setDateTo(1623074976)
->setEvent(['processed', 'sent']);
$mailersend->activity->getAll('domainId', $activityParams);
Analytics
Activity data by date
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\ActivityAnalyticsParams;
use MailerSend\Common\Constants;
$mailersend = new MailerSend(['api_key' => 'key']);
$activityAnalyticsParams = (new ActivityAnalyticsParams(100, 101))
->setDomainId('domain_id')
->setGroupBy(Constants::GROUP_BY_DAYS)
->setTags(['tag'])
->setEvent(['processed', 'sent']);
$mailersend->analytics->activityDataByDate($activityAnalyticsParams);
Opens by country
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\OpensAnalyticsParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$opensAnalyticsParams = (new OpensAnalyticsParams(100, 101))
->setDomainId('domain_id')
->setTags(['tag']);
$mailersend->analytics->opensByCountry($opensAnalyticsParams);
Opens by user-agent name
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\OpensAnalyticsParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$opensAnalyticsParams = (new OpensAnalyticsParams(100, 101))
->setDomainId('domain_id')
->setTags(['tag']);
$mailersend->analytics->opensByUserAgentName($opensAnalyticsParams);
Opens by reading environment
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\OpensAnalyticsParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$opensAnalyticsParams = (new OpensAnalyticsParams(100, 101))
->setDomainId('domain_id')
->setTags(['tag']);
$mailersend->analytics->opensByReadingEnvironment($opensAnalyticsParams);
Domains
Get all domains
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->domain->getAll($page = 1, $limit = 10, $verified = true);
Get a single domain
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->domain->find('domain_id');
Delete a domain
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->domain->delete('domain_id');
Get recipients for a domain
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->domain->recipients($domainId = 'domain_id', $page = 1, $limit = 10);
Update domain settings
Here you can set as many properties as you need, one or multiple.
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\DomainSettingsParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$domainSettingsParam = (new DomainSettingsParams())
->setSendPaused(true)
->setTrackClicks(true)
->setTrackOpens(false)
->setTrackUnsubscribe(false)
->setTrackContent(true)
->setTrackUnsubscribeHtml('html')
->setTrackUnsubscribePlain('plain')
->setCustomTrackingEnabled(true)
->setCustomTrackingSubdomain(false);
$mailersend->domain->domainSettings($domainId = 'domain_id', $domainSettingsParam);
Messages
List messages
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->messages->get($limit = 100, $page = 3);
Find a specific message
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->messages->find('message_id');
Recipients
List recipients
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->recipients->get(null, $limit = 100, $page = 3);
List recipients in a specific domain
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->recipients->get('domain_id', $limit = 100, $page = 3);
Find a specific recipient
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->recipients->find('recipient_id');
Delete a recipient
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->recipients->delete('recipient_id');
Tokens
Create a new token
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\TokenParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->token->create(
new TokenParams('token name', 'domainId', TokenParams::ALL_SCOPES)
);
Because of security reasons, we only allow access token appearance once during creation. In order to see the access token created you can do:
use MailerSend\Helpers\Builder\TokenParams;
$response = $mailersend->token->create(
new TokenParams('token name', 'domainId', TokenParams::ALL_SCOPES)
);
echo $response['body']['data']['accessToken'];
Pause / Unpause Token
use MailerSend\Helpers\Builder\TokenParams;
$mailersend->token->update('token_id', TokenParams::STATUS_PAUSE); // PAUSE
$mailersend->token->update('token_id', TokenParams::STATUS_UNPAUSE); // UNPAUSE
Delete Token
use MailerSend\Helpers\Builder\TokenParams;
$mailersend->token->delete('token_id');
Webhooks
List Webhooks
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->webhooks->get('domain_id');
Find a Webhook
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->webhooks->find('webhook_id');
Create a Webhook
use MailerSend\Helpers\Builder\WebhookParams;
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->webhooks->create(
new WebhookParams('https://webhook_url', 'Webhook name', WebhookParams::ALL_ACTIVITIES, 'domain_id')
);
Create a disabled Webhook
use MailerSend\Helpers\Builder\WebhookParams;
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->webhooks->create(
new WebhookParams('https://webhook_url', 'Webhook name', WebhookParams::ALL_ACTIVITIES, 'domain_id', false)
);
Update a Webhook
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\WebhookParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->webhooks->update('webhook_id', 'https://webhook_url', 'Webhook name', WebhookParams::ALL_ACTIVITIES);
Disable/Enable a Webhook
use MailerSend\Helpers\Builder\WebhookParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->webhooks->update('webhook_id', 'https://webhook_url', 'Webhook name', WebhookParams::ALL_ACTIVITIES, true); //Enabled
$mailersend->webhooks->update('webhook_id', 'https://webhook_url', 'Webhook name', WebhookParams::ALL_ACTIVITIES, false); //Disabled
Delete a Webhook
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->webhooks->delete('webhook_id');
If, at the moment, some endpoint is not available, please use cURL
and other available tools to access it. Refer to official API docs for more info.
Testing
composer test
Support and Feedback
In case you find any bugs, submit an issue directly here in GitHub.
You are welcome to create SDK for any other programming language.
If you have any troubles using our API or SDK free to contact our support by email [email protected]
The official documentation is at https://developers.mailersend.com