Knowledge base

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 your domain in MailerSend, follow these steps:

  1. Navigate to the Domains page.

  2. Create an API token.

  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, Java, Ruby, 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.

If your account is approved, you'll be able to send to any recipient. If not, you'll only be able to send to recipients sharing the same domain (or associated subdomain) as your verified domain.

Additionally, any email has to be sent with a FROM address matching the verified domain or an associated subdomain.

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

How to send emails using SMTP

Check that your domain is verified in MailerSend, then follow these steps:

  1. Navigate to the Domains page.

  2. Find the domain from which you want to send emails via SMTP and click Manage.

  3. Scroll down to SMTP and toggle Send emails using our SMTP servers instead of our REST API to enable SMTP sending.

  1. The following information will be automatically generated: 

  • Server

  • Port

  • Username

  • Password

SMTP credentials
  1. Enter this information into your app or via a plugin.

Note: If you’re asked to provide an encryption type, choose TLS or STARTTLS.

After sending your first email, you can check the status of your message in the Activity tab.

Same as for the API, if your account is approved, you'll be able to send to any recipient. If not, you'll only be able to send to recipients sharing the same domain (or associated subdomain) as your verified domain.

Additionally, any email has to be sent with a FROM address matching the verified domain or an associated subdomain.

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, open the account menu in the bottom left of the screen and select the respective option.

Using the MailerSend file manager.

  • 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

Screenshot of MailerSend templates page with ID highlighted.
  • In the right-side column of the Template page

A screenshot of the template page with the template ID highlighted.

The template ID is already included within the sending instructions, copy the ones for your language of choice.

How to use custom fonts in templates

To use a custom font in your email template using the drag & drop editor or HTML editor:

  1. Pick a web safe font or a web font, for example, from Google Fonts.

Note: Web fonts are custom fonts that are loaded and displayed along with the webpage. If a web font is not supported by the recipient's email client, a default web safe font like Arial or Helvetica will be displayed instead.
  1. If using Google Fonts, click + Select this style next to the font to open a side panel.

Google Fonts selection

Drag & drop editor

To use a custom font with the drag & drop editor:

  1. In Google Fonts, select <link> and copy the code.

Select <link>

In MailerSend, insert a code block below the Block Preheader and paste the code in the Custom HTML code field.

Custom HTML code
  1. Add the following code to the one that you just pasted:

<style>p { !important }</style>
Add style code
  1. Go back to the Google Fonts page and copy the code under CSS rules to specify families.

  2. Paste the code between the curly brackets { } and before !important like this:

<style>p {font-family: 'Roboto', sans-serif; !important } </style>
Add font family
Note: In this example, Roboto is the name of the web font, and Sans-serif is the style for that particular font. If the web font is not supported, the email client will display a default sans serif font.
  1. To use the custom font throughout the template—including the text, headings, and buttons—replace the p with an asterisk * like this:

<style>* {font-family: 'Roboto', sans-serif; !important }</style>
Use custom font throughout template
  1. Write the text for your email template, enclosing them in <p> tags.

Add email template text

HTML editor

For the HTML editor, you can either use the <link> or @import tags from Google Fonts.

If you’re using the <link> tag:

  1. Copy the <link> tag from Google Fonts and paste it inside the <head> part of your template in MailerSend.

Insert <link> tag
  1. Then define the font family by adding the following code to the <style> tag:

<style type=”text/css”>body {font-family: 'Roboto', sans-serif;}</style>
Add font family tag

Your template will now display the custom font for the body of your email.

If you’re using the @import tag:

  1. Copy the @import tag from Google Fonts and paste inside the <head> part of your template in MailerSend.

Add @import tag

2. Then define the font family by adding the following code to the <style> tag:

body {font-family: 'Roboto', sans-serif;}
Add body tag

Your template will now display the custom font for the body of your email.

How to troubleshoot emails not sending

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

To start troubleshooting both API and SMTP connections:

  • Check the FROM email you're sending from. It must match the verified domain that the API token or SMTP credentials belong to

  • Check your credentials. Your API token or your SMTP credentials must be valid and authorized before you can start sending emails

To start troubleshooting API requests:

  • Make sure you're providing either a valid HTML, a text version, or a template ID. One of these three parameters has to be included in your API request

  • Verify that 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. See all API response codes you might encounter on the Developers' documentation.

The most common ones are:

400

Bad request

401

Unauthorized

403

Forbidden

405

Method not allowed

408

Request timeout

422

Unprocessable entity - validation error

422 - unprocessable entity

422 errors can encompass multiple errors types, the most common include:

From email must be verified

The domain of the from email address must match the domain that the API token or SMTP credentials are from.

You must provide HTML and/or text versions of the email or template ID.

The API request is missing one of the 3 parameters needed to send the content, either the text or HTML version or the template ID.

This file type is not supported.

The attachment file encoded in Base 64 is not part of our supported filetypes. Please refer to our supported filetypes here.

The reply to email must be a valid email address.

The reply_to email parameter is not a valid email address, it may be missing an "@", make sure it's a valid email address without typos.

Email quota reached

The account's quota has been reached. Make sure your account has been approved so you can send more than 100 emails per month.

Rejected emails

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 from being abused by spammers—protecting the sender's reputation of all that server’s users.

MailerSend rate limits

MailerSend has a default rate limit on all endpoints. If you exceed that rate limit, you will receive a 429 error response with a “Too Many Attempts.” message. See all rate limits here.

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

API requests to v1/bulk-email

10 requests to v1/bulk-email per minute

SMTP

120 requests/minute

Need more info?

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

Stop War! Help Ukraine! See what you can do