Sending an Email
This endpoint allows you to start sending emails through the MailerSend Email API.
Send an email
This endpoint allows you to send an asynchronous email. It returns the status of the email sent with an x-message-id that can be used to continuously query for the status using the Email API.
Send an email using this POST request:
POST https://api.mailersend.com/v1/email
Request Body
{
"from": {
"email": "hello@mailersend.com",
"name": "MailerSend"
},
"to": [
{
"email": "john@mailersend.com",
"name": "John Mailer"
}
],
"subject": "Hello from {{company}}!",
"text": "This is just a friendly hello from your friends at {{company}}.",
"html": "<b>This is just a friendly hello from your friends at {{company}}.</b>",
"personalization": [
{
"email": "john@mailersend.com",
"data": {
"company": "MailerSend"
}
}
]
}
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('your@client.com', 'Your Client'),
];
$emailParams = (new EmailParams())
->setFrom('your@domain.com')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject')
->setHtml('This is the HTML content')
->setText('This is the text content')
->setReplyTo('reply to')
->setReplyToName('reply to name');
$mailersend->email->send($emailParams);
import 'dotenv/config';
import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const sentFrom = new Sender("you@yourdomain.com", "Your name");
const recipients = [
new Recipient("your@client.com", "Your Client")
];
const emailParams = new EmailParams()
.setFrom(sentFrom)
.setTo(recipients)
.setReplyTo(sentFrom)
.setSubject("This is a Subject")
.setHtml("<strong>This is the HTML content</strong>")
.setText("This is the text content");
await mailerSend.email.send(emailParams);
from mailersend import emails
api_key = "API key here"
mailer = emails.NewEmail(api_key)
# define an empty dict to populate with mail values
mail_body = {}
mail_from = {
"name": "Your Name",
"email": "your@domain.com",
}
recipients = [
{
"name": "Your Client",
"email": "your@client.com",
}
]
reply_to = [
{
"name": "Name",
"email": "reply@domain.com",
}
]
mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello!", mail_body)
mailer.set_html_content("This is the HTML content", mail_body)
mailer.set_plaintext_content("This is the text content", mail_body)
mailer.set_reply_to(reply_to, mail_body)
# using print() will also return status code and data
mailer.send(mail_body)
package main
import (
"context"
"fmt"
"time"
"github.com/mailersend/mailersend-go"
)
var APIKey = "Api Key Here"
func main() {
// Create an instance of the mailersend client
ms := mailersend.NewMailersend(APIKey)
ctx := context.Background()
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
subject := "Subject"
text := "This is the text content"
html := "<p>This is the HTML content</p>"
from := mailersend.From{
Name: "Your Name",
Email: "your@domain.com",
}
recipients := []mailersend.Recipient{
{
Name: "Your Client",
Email: "your@client.com",
},
}
// Send in 5 minute
sendAt := time.Now().Add(time.Minute * 5).Unix()
tags := []string{"foo", "bar"}
message := ms.Email.NewMessage()
message.SetFrom(from)
message.SetRecipients(recipients)
message.SetSubject(subject)
message.SetHTML(html)
message.SetText(text)
message.SetTags(tags)
message.SetSendAt(sendAt)
message.SetInReplyTo("client-id")
res, _ := ms.Email.Send(ctx, message)
fmt.Printf(res.Header.Get("x-message-id"))
}
import com.mailersend.sdk.Email;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
public void sendEmail() {
Email email = new Email();
email.setFrom("name", "your email");
email.addRecipient("name", "your@recipient.com");
// you can also add multiple recipients by calling addRecipient again
email.addRecipient("name 2", "your@recipient2.com");
// there's also a recipient object you can use
Recipient recipient = new Recipient("name", "your@recipient3.com");
email.addRecipient(recipient);
email.setSubject("Email subject");
email.setPlain("This is the text content");
email.setHtml("<p>This is the HTML content</p>");
MailerSend ms = new MailerSend();
ms.setToken("Your API token");
try {
MailerSendResponse response = ms.send(email);
System.out.println(response.messageId);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
require "mailersend-ruby"
# Intialize the email class
ms_email = Mailersend::Email.new
# Add parameters
ms_email.add_recipients("email" => "ron@parksandrec.com", "name" => "Ron")
ms_email.add_recipients("email" => "leslie@parksandrec.com", "name" => "Leslie")
ms_email.add_from("email" => "april@parksandrec.com", "name" => "April")
ms_email.add_subject("Time")
ms_email.add_text("Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.")
ms_email.add_html("<b>Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.</b>")
# Send the email
ms_email.send
Request parameters
JSON parameters are provided in dot notation
| JSON parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
from | object | yes * | Not required if template_id is present and template has default sender set. | |
from.email | string | yes * | Must be a verified domain or a subdomain from a verified domain . | Not required if template_id is present and template has default sender set. |
from.name | string | no | from.email will be used if not provided or, if template_id is present with default values, the default subject from that will be used. | |
to | object[] | yes | Min 1, max 50 | |
to.*.email | string | yes | ||
to.*.name | string | no | The name of the recipient. May not contain ; or ,. | |
cc | object[] | no | Max 10 | |
cc.*.email | string | yes | ||
cc.*.name | string | no | The name of the CC recipient. May not contain ; or ,. | |
bcc | object[] | no | Max 10 | |
bcc.*.email | string | yes | ||
bcc.*.name | string | no | The name of the BCC recipient. May not contain ; or ,. | |
reply_to.email | string | no | ||
reply_to.name | string | no | ||
subject | string | yes * | Max 998 | Not required if template_id is present and template has default subject set. |
text | string | yes * | Max size of 2 MB. | Email represented in a text (text/plain) format. * Only required if there's no html or template_id present. |
html | string | yes * | Max size of 2 MB. | Email represented in HTML (text/html) format. * Only required if there's no text or template_id present. |
attachments | object[] | no | ||
attachments.*.content | string | yes | Max size of 25MB. After decoding Base64 | Base64 encoded content of the attachment. |
attachments.*.disposition | string | yes | Must be one of the attachment types: inline, attachment | Use inline to make it accessible for content. use attachment to normal attachments |
attachments.*.filename | string | yes | ||
attachments.*.id | string | no | Can be used in content as <img src="cid:*"/>. Must also set attachments.*.disposition as inline. | |
template_id | string | yes * | * Only required if there's no text or html present. | |
tags | string[] | no | Limit is max 5 tags. If the template used already has tags, then the request will override them. | |
personalization | object[] | no | Allows using personalization in {{var}} syntax. Can be used in the subject, html, text fields. Read more about advanced personalization. | |
personalization.*.email | string | yes | Email address that personalization will be applied to. | |
personalization.*.data | object[] | yes | Object with key: value pairs. Values will be added to your template using {{key}} syntax. | |
precedence_bulk | boolean | no | This parameter will override domain's advanced settings | |
send_at | integer | no | min: now, max: now + 72hours | Has to be a Unix timestamp. Please note that this timestamp is a minimal guarantee and that the email could be delayed due to server load. |
in_reply_to | string | no | Alphanumeric which can contain _, -, @ and .. | |
references | string[] | no | List of Message-ID's that the current email is referencing. Read more about creating email threads. | |
settings | object | no | ||
settings.* | boolean | yes | Can only contain the keys: track_clicks, track_opens and track_content and a boolean value of true or false. | |
headers | object[] | no | Please note that this feature is available to Professional and Enterprise accounts only | |
headers.*.name | string | yes | Must be alphanumeric which can contain - | |
headers.*.value | string | yes |
Supported file types
| File type | Extensions |
|---|---|
| Text files | .txt, .csv, .log, .css, .ics .xml |
| Image files | .jpg, .jpe, .jpeg, .gif, .png, .bmp, .psd, .tif, .tiff, .svg, .indd, .ai, .eps |
| Document files | .doc, .docx, .rtf, .odt, .ott, .pdf, .pub, .pages, .mobi, .epub |
| Audio files | .mp3, .m4a, .m4v, .wma, .ogg, .flac, .wav, .aif, .aifc, .aiff |
| Video files | .mp4, .mov, .avi, .mkv, .mpeg, .mpg, .wmv |
| Spreadsheet files | .xls, .xlsx, .ods, .numbers |
| Presentation files | .odp, .ppt, .pptx, .pps, .key |
| Archive files | .zip, .vcf |
Note
If a scheduled email is sent with a template, and that template is deleted before the sending is triggered, the scheduled email will not be sent.
Responses
Sending queued
Response Code: 202 Accepted
Response Headers:
content-type: text/plain; charset=utf-8
x-message-id: 5e42957d51f1d94a1070a733
Response Body: [EMPTY]
Sending paused
Response Code: 202 Accepted
Response Headers:
content-type: text/plain; charset=utf-8
x-message-id: 5e42957d51f1d94a1070a733
x-send-paused: true
Response Body: [EMPTY]
Validation error
Response Code: 422 Unprocessable Entity
Response Headers:
content-type: application/json
{
"message": "The given data was invalid.",
"errors": {
"from.email": [
"The from.email domain must be verified in your account to send emails. #MS42207"
]
}
}
See - Validation errors
Validation warning
Response Code: 202 Accepted
Response Headers:
content-type: application/json
x-message-id: 5e42957d51f1d94a1070a733
{
"message": "There are some warnings for your request.",
"warnings": [
{
"type": "SOME_SUPPRESSED",
"warning": "Some of the recipients have been suppressed.",
"recipients": [
{
"email": "suppressed@recipient.com",
"name": "Suppressed Recipient",
"reasons": ["blocklisted"]
}
]
}
]
}
Send encrypted emails
You can use MailerSend to send encrypted messages using S/MIME or PGP. The sender encrypts messages that use these protocols. Their contents can only be viewed by recipients with the private keys required to decrypt the messages.
MailerSend supports the following MIME types, which you can use to send S/MIME encrypted emails:
application/pkcs7-mime
application/pkcs7-signature
application/x-pkcs7-mime
application/x-pkcs7-signature
MailerSend also supports the following MIME types, which you can use to send PGP-encrypted emails:
application/pgp-encrypted
application/pgp-keys
application/pgp-signature
Send bulk emails
This endpoint allows you to send multiple asynchronous emails. It returns the status of the request sent with a bulk_email_id that can be used to continuously query for the status using the Email API.
To prevent long waiting periods for a response, each email validation is done after the request and then the result is stored. If there is any validation error, you can query it using the bulk_email_id provided.
Send a bulk email using this POST request:
POST https://api.mailersend.com/v1/bulk-email
Request Body
[
{
"from": {
"email": "hello@mailersend.com",
"name": "MailerSend"
},
"to": [
{
"email": "john@mailersend.com",
"name": "John Mailer"
}
],
"subject": "Hello from {{company}}!",
"text": "This is just a friendly hello from your friends at {{company}}.",
"html": "<b>This is just a friendly hello from your friends at {{company}}.</b>",
"personalization": [
{
"email": "john@mailersend.com",
"data": {
"company": "MailerSend"
}
}
]
},
{
"from": {
"email": "hello@mailersend.com",
"name": "MailerSend"
},
"to": [
{
"email": "jane@mailersend.com",
"name": "Jane Mailer"
}
],
"subject": "Welcome to {{company}}!",
"text": "This is a welcoming message from your friends at {{company}}.",
"html": "<b>This is a welcoming message from your friends at {{company}}.</b>",
"personalization": [
{
"email": "jane@mailersend.com",
"data": {
"company": "MailerSend"
}
}
]
}
]
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;
$mailersend = new MailerSend(['api_key' => 'key']);
$recipients = [
new Recipient('your@client.com', 'Your Client'),
];
$bulkEmailParams = [];
$bulkEmailParams[] = (new EmailParams())
->setFrom('your@domain.com')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject')
->setHtml('This is the HTML content')
->setText('This is the text content');
$bulkEmailParams[] = (new EmailParams())
->setFrom('your@domain.com')
->setFromName('Your Name')
->setRecipients($recipients)
->setSubject('Subject')
->setHtml('This is the HTML content')
->setText('This is the text content');
$mailersend->bulkEmail->send($bulkEmailParams);
import 'dotenv/config';
import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
const sentFrom = new Sender("your@yourdomain.com", "Your name");
const bulkEmails = [];
const emailParams = new EmailParams()
.setFrom(sentFrom)
.setTo([
new Recipient("your@client.com", "Your Client")
])
.setSubject("This is a Subject")
.setHtml("<strong>This is the HTML content</strong>")
.setText("This is the text content");
bulkEmails.push(emailParams);
const emailParams2 = new EmailParams()
.setFrom(sentFrom)
.setTo([
new Recipient("your_2@client.com", "Your Client 2")
])
.setSubject("This is a Subject 2")
.setHtml("<strong>This is the HTML content 2</strong>")
.setText("This is the text content 2");
bulkEmails.push(emailParams2);
await mailerSend.email.sendBulk(bulkEmails);
from mailersend import emails
api_key = "API key here"
mailer = emails.NewEmail(api_key)
mail_list = [
{
"from": {
"email": "your@domain.com",
"name": "Your Name"
},
"to": [
{
"email": "your@client.com",
"name": "Your Client"
}
],
"subject": "Subject",
"text": "This is the text content",
"html": "<p>This is the HTML content</p>",
},
{
"from": {
"email": "your@domain.com",
"name": "Your Name"
},
"to": [
{
"email": "your@client.com",
"name": "Your Client"
}
],
"subject": "Subject",
"text": "This is the text content",
"html": "<p>This is the HTML content</p>",
}
]
print(mailer.send_bulk(mail_list))
package main
import (
"context"
"time"
"log"
"fmt"
"github.com/mailersend/mailersend-go"
)
var APIKey = "Api Key Here"
func main() {
// Create an instance of the mailersend client
ms := mailersend.NewMailersend(APIKey)
ctx := context.Background()
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
subject := "Subject"
text := "This is the text content"
html := "<p>This is the HTML content</p>"
from := mailersend.From{
Name: "Your Name",
Email: "your@domain.com",
}
recipients := []mailersend.Recipient{
{
Name: "Your Client",
Email: "your@client.com",
},
}
var messages []*mailersend.Message
for i := range [2]int{} {
msg := &mailersend.Message{
From: from,
Recipients: recipients,
Subject: fmt.Sprintf("%s %v", subject, i),
Text: text,
HTML: html,
}
messages = append(messages, msg)
}
_, _, err := ms.BulkEmail.Send(ctx, messages)
if err != nil {
log.Fatal(err)
}
}
import com.mailersend.sdk.emails.Email;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
public void sendBulkEmails() {
Email email1 = new Email();
email1.setFrom("name", "your email");
email1.addRecipient("name", "your@first-recipient.com");
email1.setSubject("Email subject 1");
email1.setPlain("This is the text content for the first email");
email1.setHtml("<p>This is the HTML content for the first email</p>");
Email email2 = new Email();
email2.setFrom("name", "your email");
email2.addRecipient("name", "your@second-recipient.com");
email2.setSubject("Email subject 2");
email2.setPlain("This is the text content for the second email");
email2.setHtml("<p>This is the HTML content for the second email</p>");
MailerSend ms = new MailerSend();
ms.setToken("Your API token");
try {
String bulkSendId = ms.emails().bulkSend(new Email[] { email1, email2 });
// you can use the bulkSendId to get the status of the emails
System.out.println(bulkSendId);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
require "mailersend-ruby"
ms_bulk_email = Mailersend::BulkEmail.new
ms_bulk_email.messages = [
{
'from' => {"email" => "april@parksandrec.com", "name" => "April"},
'to' => [{"email" => "ron@parksandrec.com", "name" => "Ron"}],
'subject' => "Time",
'text' => "Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.",
'html' => "<b>Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.</b>",
},
{
'from' => {"email" => "april@parksandrec.com", "name" => "April"},
'to' => [{"email" => "leslie@parksandrec.com", "name" => "Leslie"}],
'subject' => "Lorem Ipsum",
'text' => "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
'html' => "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
}
]
ms_bulk_email.send
Request parameters
JSON parameters are provided in dot notation
| JSON parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
* | object[] | yes | Must be an array. | Array of email objects. |
*.* | object | yes | Must be an email object. | See email object for detailed options available. |
Limitations
| Description | Limit |
|---|---|
| Total size of the JSON payload | 50MB |
| Number of individual email objects in a single request | 5 for Trial plan accounts. 500 for Hobby, Starter, Professional or Enterprise plan accounts. |
| Number of recipients per email object. | See Email endpoint. |
| API requests per minute | 10 for Trial and Hobby plan accounts. 15 for Starter plan accounts. 30 for Professional plan accounts. 60 for Enterprise plan accounts. |
If not mentioned, the limits are the same as for the generic Email API endpoint.
Responses
Response Code: 202 Accepted
Response Headers:
content-type: application/json
{
"message": "The bulk email is being processed. Read the Email API to know how you can check the status.",
"bulk_email_id": "614470d1588b866d0454f3e2"
}
Errors
Validation errors
Validation errors, as well as any other issues like failed emails, are stored in the database. You can check them by calling the 'Get bulk email' endpoint.
Validation errors are indexed by the order they are sent: message.{order_index}.
Suppression errors
If one or more recipients specified in the messages are suppressed, similarly to the validation errors, they are stored and can be checked with the 'Get bulk email' endpoint.
The suppression errors are indexed by x-message-id.
Get bulk email status
Get the bulk email information like validation errors, failed emails and more.
Check the bulk email status using this GET request:
GET https://api.mailersend.com/v1/bulk-email/{bulk_email_id}
Request parameters
| URL parameter | Type | Required | Limitations | Details |
|---|---|---|---|---|
bulk_email_id | string | yes |
use MailerSend\MailerSend;
$mailersend = new MailerSend(['api_key' => 'key']);
$mailersend->bulkEmail->getStatus('bulk_email_id');
import 'dotenv/config';
import { MailerSend } from "mailersend";
const mailerSend = new MailerSend({
apiKey: process.env.API_KEY,
});
mailerSend.email.getBulkStatus('bulk_email_id') // bulk email Id e.g 63af1fdb790d97105a090001
.then((response) => {
console.log(response.body);
});
from mailersend import emails
api_key = "API key here"
mailer = emails.NewEmail(api_key)
print(mailer.get_bulk_status_by_id("bulk-email-id"))
package main
import (
"context"
"time"
"log"
"github.com/mailersend/mailersend-go"
)
var APIKey = "Api Key Here"
func main() {
// Create an instance of the mailersend client
ms := mailersend.NewMailersend(APIKey)
ctx := context.Background()
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
_, _, err := ms.BulkEmail.Status(ctx, "bulk-email-id")
if err != nil {
log.Fatal(err)
}
}
import com.mailersend.sdk.emails.Email;
import com.mailersend.sdk.emails.BulkSendStatus;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;
public void getBulkEmailsStatus() {
MailerSend ms = new MailerSend();
ms.setToken("Your API token");
try {
BulkSendStatus status = ms.emails().bulkSendStatus("bulk send id");
System.out.println(status.state);
} catch (MailerSendException e) {
e.printStackTrace();
}
}
require "mailersend-ruby"
ms_bulk_email = Mailersend::BulkEmail.new
ms_bulk_email.get_bulk_status(bulk_email_id: 'yourbulkemailid')
Responses
Valid
Response Code: 200 OK
Response Headers:
content-type: application/json
{
"data": {
"id": "614470d1588b866d0454f3e2",
"state": "completed",
"total_recipients_count": 1,
"suppressed_recipients_count": 0,
"suppressed_recipients": null,
"validation_errors_count": 0,
"validation_errors": null,
"messages_id": "['61487a14608b1d0b4d506633']",
"created_at": "2021-09-17T10:41:21.892000Z",
"updated_at": "2021-09-17T10:41:23.684000Z"
}
}
Invalid
Response Code: 404 Not Found