How to start sending emails

Before you can start sending emails with MailerSend, you first need to have at least one domain verified. Check our article on How to verify and authenticate a sending domain for further instructions.

Make sure you check our developer documentation, where you can find all available parameters that help you send better and more complex emails through MailerSend.

How to send emails using API

Once you have verified and authenticated your domain in MailerSend, follow these steps:

  1. Navigate to the Domains page.

  2. Create an API token if you haven’t yet.

  3. When your API token is ready, scroll down to the Sending instructions section of the page. You’ll find a few examples of how to send your emails using cURL, PHP, Laravel, Node.js, Go and Python

  4. The easiest way to start sending emails is by copying and pasting the cURL command into your terminal by sending a POST request to https://api.mailersend.com/v1/email

Note: Don’t forget that you need to replace the API token, FROM, and TO values that are included in the cURL command.

Once you send your first email, you can check the status of your message in the Activity tab.

How to add CC and BCC recipients

CC and BCC recipients can be included in emails sent both via API or SMTP.

To include CC and BCC recipients in your sending, simply copy the recipients block

{to:”email”: “recipient@example.com”}

and replace “to” with one of the following parameters.

JSON parameter

Type

Required

Limitations

cc

object [ ]

No

Max 10

bcc

object [ ]

No

Max 10

Note: Limitations refer to verified domains. If your domain is unverified, you may only include one CC and BCC recipient.

CC and BCC example

{

"from": {

"email": "hello@example.com"

},

"to": [

{

"email": "recipient1@gmail.com"

}

],

"cc": [

{"email": "recipient2@gmail.com"},

    {"email": "recipient3@gmail.com"},

    {"email": "recipient4@gmail.com"},

    {"email": "recipient5@gmail.com"}

],

"bcc": [

{

"email": "recipient6@gmail.com"
}
],
Remember: Suppression rules still apply to recipients who are entered as a CC or BCC. If a suppressed recipient is the primary recipient, the email will not send to any recipients.

How to add media and attachment files

There are 4 different JSON parameters that you can use to add media and attachment files into your emails sent via API, which you can find on our Developer documentation.

The attachments you can send include PDF files, Office documents, images, zip files, video files, and more. The attachment file has to be less than 10MB in size.

To send an attachment, you can:

  • Upload a file to your File manager (or host your file on any other server) and use its URL in the response body of the API call. This would redirect the recipients to open a new tab where the file can be downloaded.

    To open your File manager, click on the dropdown arrow located on the top-right corner of your screen and select the respective option.

  • Use Base64 to encode your file and include it within a JSON parameter.

JSON parameter

Type

Required

Details

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

Here is an example of how a JSON parameter could look in the response body of an API call:

{
  "attachments": [
     {
       "content": "iVBORw0KGgoAAAANSUhEUgAAC0AAAAcICAYAAACv5EAVAAAEGWlDQ1",
       "filename": "logo.png",
       "id": "logo.png"
     }
   ]
}

How to add triggers and automations via Zapier

Zapier is a web-based application that allows you to connect hundreds of different applications with one another.

In MailerSend, you can use both API and webhooks to connect to Zapier, which you can find on your Domains page. Zapier uses our API to execute action events and webhooks to create trigger events.

To create an API token, head to Domains and select the domain you want to use. On the domain’s page, you will find the API section where you can create and manage each entry.

There are 7 trigger events:

  • Email is sent

  • Email is delivered

  • Email is opened

  • Email is clicked

  • Email is soft-bounced

  • Email is hard-bounced

  • Recipient has unsubscribed

There are 2 action events:

  • Send an email

  • Send a template-based email

For a more detailed exploration of what you can do with MailerSend, check the How to create automations with Zapier article.

How to personalize your emails

In MailerSend, you can use both simple and advanced personalization. Check our Developer documentation for more details on how to include personalization using API calls. 

Simple personalization

You can input basic data by using variables in the {$variable} format for each recipient when sending emails using the Email API endpoint to personalize your emails in the subject, html, and text fields. 

It begins with a curly bracket {, followed by a dollar sign $, then the name of the variable, and is finally closed with the opposite curly bracket }: {$variable}. 

An example of a text with simple personalization could read: “Hi {$name}. Thank you for shopping with us all the way from {$country}!

This type of personalization has the following rules:

  • It must be enclosed within curly brackets

  • It must include the name of the variable after the dollar sign ($)

  • It may contain alphanumeric characters and underscores (_)

  • It cannot start with numbers or an underscore

  • It is case-sensitive, which means that {$VAR} is different than {$var}

Note that the data of this variable should be stored wherever you are making the API calls from.  

Advanced personalization

You can generate dynamic content for each recipient when sending emails using the Email API endpoint to personalize your emails in the subject, html, and text fields. 

Keep in mind that:

  • Advanced personalization only compiles the template if personalization data is passed via Email API

  • It is cached server-side, but the hash is calculated based on content, so it will reset with every change

Variables

The variable should begin with double curly brackets {{, followed by a space, then the name of the variable, then another space, and finally closed with double opposite curly brackets }}{{ variable }}

When using a variable, keep in mind that:

  • It must be enclosed within double curly brackets {{ variable }}

  • It may contain alphanumeric characters and underscores (_)

  • It must not start with a number or underscore

  • It is case-sensitive, which means that {{ VAR }} is different from {{ var }}

Conditional statement

You can show different content to each recipient if they meet a certain condition. 

The conditional statement should always be included between the {% %} block. It should start with the if keyword, followed by the statement being tested, and end with the endif keyword. 

It’s also possible to nest if statements inside one another, including the use of the elseif and else keywords before endif, although not necessary.

For example, let’s say you’re letting your recipients know you’re having a sale of a specific item and only have limited stock. To point out whether the item is still available for sale or not, you could write the following piece of code:

{% if boolean == true %}
   Available
{% elseif number > 0 %}
   Only {{ number }} left!
{% else %}
   Sold-out!
{% endif %}

The output of this code would show Available if there’s enough stock, Only number left if there’s a shortage of items, or Sold-out! if there aren’t any items left in stock. 

You can also use filters, which basically modify something in the value of the variable. They are separated from the variable by the pipe symbol |

The filters you can use are escape, length, lower, upper, and keys.

An example of using the length filter could be:

{% if users|length > 10 %}
   ...
{% endif %}

Foreach

You can print the data of an array, or a collection of data, by looping through each of its items. 

The loop should be included between the {% %} block, start with the for keyword and end with the endfor keyword. 

You can also use filters, which basically modify something in the value of the variable. They are separated from the variable by the pipe symbol |

The filters you can use are escape, length, lower, upper, and keys.

For example, let’s say you want to print out a grocery shopping list. You could use the following piece of code:

{% if array|length > 0 %}
   <ul>
        {% for value in array %}
           <li>{{ value }}</li>
        {% endfor %}
   </ul>
{% endif %}

The final result would render:

  • Potatoes

  • Rice

  • Beans

How to use MailerSend templates

To explore the pre-made templates or create your own:

  1. Head to Templates.

  2. Click Create template.

  3. Choose whether you want to write or import your own HTML template, use our Rich-text editor or our Drag & drop editor.

  4. Once you are satisfied with the email design, make sure you name the template and click on Save changes.

  5. You can find the Sending instructions at the bottom of the page, for which cURL, PHP or Laravel can be used.

Each template has its own ID, which you can find in 2 places: 

  • The main Templates page, under the template’s name

  • At the top-right corner of the same page where you find the sending instructions

    Include the template ID within the sending instructions:

  • For cURL, paste it between the quotation marks “ “ for template_id.

  • For PHP, include it between the apostrophes ‘ ’ for setTemplateId.

  • For Laravel, include it between the apostrophes ‘ ’ for mailersend.

How to troubleshoot emails not sending

When trying to send an email via an API request, you may come across an error that prevents the email from being sent or received.

To start troubleshooting:

  • Check your API token. It must be valid and authorized before you can start sending emails via API. Take a look at our Managing API tokens article if you need more information

  • Make sure you are including all relevant headers and are using them correctly

  • Verify if you’re using the correct API request, which should be POST https://api.mailersend.com/v1/email

  • Check that all of the JSON parameters in the body are properly enclosed and there aren’t any typos

REST API response codes 

If there’s an issue with successfully submitting an API request, you will get a numbered response code, which is specific to a client-side error. 

The most common ones are:

400

Bad request

401

Unauthorized

403

Forbidden

405

Method not allowed

408

Request timeout

422

Unprocessable entity - validation error

You can also verify the status of the email by using the GET request with the ID of the email sent.

soft_bounced

Your email was not delivered because it soft-bounced. A soft bounce is a temporary rejection by a receiving recipient’s server. This may happen because the recipient's inbox is full.

hard_bounced

Your message was not delivered. The message was returned to our servers because the recipient's address is invalid. A hard bounce may occur because the domain name does not exist or because the recipient is unknown. You will not be able to send future email messages to recipients that hard bounced. Use the Suppressions tool to check and manage all rejected recipients.

junk

Your message was sent to your recipient’s junk folder.

unsubscribed

Your message was rejected because the recipient's email address is in your Suppression list.

spam_complaints

Similarly, your message was rejected because the recipient's email address is in your Suppression list.

What are MailerSend’s rate limits?

Rate limits restrict the number of requests a user can make per minute. They exist to protect shared servers being abused by spammers—protecting the sender reputation of all that server’s users.

MailerSend rate limits

Request type

Rate limit

All API requests (excluding v1/email)

60 requests per minute.

API requests to v1/email

120 requests to v1/email per minute.

SMTP emails

300 requests per minute.

Need more info?

Feel free to talk with us via live chat or contact us at support@mailersend.com.