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
1

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>",
  "variables": [
    {
      "email": "john@mailersend.com",
      "substitutions": [
        {
          "var": "company",
          "value": "MailerSend"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Request parameters

JSON parameters are provided in dot notation

JSON parameterTypeRequiredLimitationsDetails
fromobjectyes *Not required if template_id is present and template has default sender set.
from.emailstringyes *Must be a verified domain.Not required if template_id is present and template has default sender set.
from.namestringnofrom.email will be used if not provided or, if template_id is present with default values, the default subject from that will be used.
toobject[]yesMin 1, max 50
to.*.emailstringyes
to.*.namestringnoThe name of the recipient. May not contain ; or ,.
ccobject[]noMax 10
cc.*.emailstringyes
cc.*.namestringnoThe name of the CC recipient. May not contain ; or ,.
bccobject[]noMax 10
bcc.*.emailstringyes
bcc.*.namestringnoThe name of the BCC recipient. May not contain ; or ,.
reply_to.emailstringno
reply_to.namestringno
subjectstringyes *Not required if template_id is present and template has default subject set.
textstringyes *Max size of 2 MB.Email represented in a text (text/plain) format. * Only required if there's no html or template_id present.
htmlstringyes *Max size of 2 MB.Email represented in HTML (text/html) format. * Only required if there's no text or template_id present.
attachmentsobject[]no
attachments.*.contentstringyesMax size of 10MB. After decoding Base64Base64 encoded content of the attachment.
attachments.*.filenamestringyes
attachments.*.idstringnoCan be used in content as an <img/> tag. TBD
template_idstringyes ** Only required if there's no text or html present.
tagsstring[]noLimit is max 5 tags.
variablesobject[]noThese will be replaced in the email content using {$var} format. Can be used in the subject, html, text fields.
variables.*.emailstringyesEmail address that substitutions will be applied to. Read more about simple personalization.
variables.*.substitutionsobject[]yes
variables.*.substitutions.*.varstringyesName of the variable, will replace {$var} in the subject, html, text fields.
variables.*.substitutions.*.valuestringyesValue to be replaced, based on the variables.*.substitutions.*.var name.
personalizationobject[]noAllows using personalization in {{ var }} syntax. Can be used in the subject, html, text fields. Read more about advanced personalization.
personalization.*.emailstringyesEmail address that personalization will be applied to.
personalization.*.dataobject[]yesObject with key: value pairs. Values will be added to your template using {{ key }} syntax.
precedence_bulkbooleannoThis parameter will override domain's advanced settings
send_atintegernomin: now, max: now + 72hoursHas to be a Unix timestampopen in new window. Please note that this timestamp is a minimal guarantee and that the email could be delayed due to server load.

Supported file types

File typeExtensions
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

Responses

Sending queued

Response Code: 202 Accepted
Response Headers:
	Content-Type: text/plain; charset=utf-8
	X-Message-Id: 5e42957d51f1d94a1070a733
Response Body: [EMPTY]
1
2
3
4
5

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]
1
2
3
4
5
6

Validation error

Response Code: 422 Unprocessable Entity
Response Headers:
	Content-Type: application/json
1
2
3
{
  "message": "The given data was invalid.",
  "errors": {
    "from.email": [
      "The from.email must be verified."
    ]
  }
}
1
2
3
4
5
6
7
8

See - Validation errors

Validation warning

Response Code: 202 Accepted
Response Headers:
	Content-Type: application/json
	X-Message-Id: 5e42957d51f1d94a1070a733
1
2
3
4
{
  "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"]
    		}
  		]
  	}
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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
1

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>",
    "variables": [
      {
        "email": "john@mailersend.com",
        "substitutions": [
          {
            "var": "company",
            "value": "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>",
    "variables": [
      {
        "email": "jane@mailersend.com",
        "substitutions": [
          {
            "var": "company",
            "value": "MailerSend"
          }
        ]
      }
    ]
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

Request parameters

JSON parameters are provided in dot notation

JSON parameterTypeRequiredLimitationsDetails
*object[]yesMust be an array.Array of email objects.
*.*objectyesMust be an email object.See email object for detailed options available.

Limitations

DescriptionLimit
Total size of the JSON payload50MB
Number of individual email objects in a single request5 for no plan accounts;
500 for Free and Premium plan accounts.
Number of recipients per email object.See Email endpoint.
API requests per minute10

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
1
2
3
{
  "message": "The bulk email is being processed. Read the Email API to know how you can check the status.",
  "bulk_email_id": "614470d1588b866d0454f3e2"
}
1
2
3
4

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}
1

Request parameters

URL parameterTypeRequiredLimitationsDetails
bulk_email_idstringyes

Responses

Valid

Response Code: 200 OK
Response Headers:
	Content-Type: application/json
1
2
3
{
  "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"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Invalid

Response Code: 404 Not Found
1
Last Updated: