# Email

This endpoint allows you to start sending emails through MailerSend Email API.

# Send an email

This endpoint allows you to send an asynchronous email. It returns the status of the email sent with a 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>",
  "variables": [
    {
      "email": "john@mailersend.com",
      "substitutions": [
        {
          "var": "company",
          "value": "MailerSend"
        }
      ]
    }
  ]
}

# 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 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 * not required if template_id is present and template has default subject set
text string yes * Email represented in a text (text/plain) format. * Only required if there's no template_id present.
html string no Email represented in HTML (text/html) format.
attachments object[] no
attachments.*.content string yes Base64 encoded content of the attachment
attachments.*.filename string yes
attachments.*.id string no Can be used in content as an <img/> tag. TBD
template_id string no
tags string[] no Limit is max 5 tags
variables object[] no These will be replaced in the email content using {$var} format. Can be used in the subject, html, text fields.
variables.*.email string yes Email address that substitutions will be applied to. More about simple personalization
variables.*.substitutions object[] yes
variables.*.substitutions.*.var string yes Name of the variable, will replace {$var} in the subject, html, text fields.
variables.*.substitutions.*.value string yes Value to be replaced, based on the variables.*.substitutions.*.var name
personalization object[] no It allows using a personalization in {{ var }} syntax. Can be used in the subject, html, text fields. More about advanced personalziation
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.

# 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

# 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 must be verified."
    ]
  }
}

See - Validations 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 bulk emails

This endpoint allows you to send multiple asynchronous emails. It returns the status of the request sent with an 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 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>",
    "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"
          }
        ]
      }
    ]
  }
]

# Request parameters

JSON parameters are provided in dot notation

JSON parameter Type Required Limitations Details
* object[] yes Must be an array. Array of emails 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 no plan accounts;
500 for Free and Premium plan accounts;
Number of recipients per email object. See Email endpoint.
API requests per minute 10

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

The validation errors, as well as any other issues like the failed emails, are stored in the database. You can check them by calling the 'Get bulk email' endpoint.

The 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

# 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
Last updated: 11/29/2021, 1:49:54 PM