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 and click Manage next to the desired domain.

2. Create an API token.

3. When your API token is ready, and scroll down to the Advanced settings section of the page. Under API instructions, 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. 

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

4. Click Generate new user.

By creating SMTP users, the following information will be automatically generated:

• Username

• Password

1. You will be required to enter this information into your content management system either directly or via a plugin. Either way, all systems will require you to enter your Server (SMTP host), Port, Username and Password.

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

Just like with 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": "info@mailersend.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

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"
	}
	]

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 25MB 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.

• 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 the management page of each Domain. 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 } as so: {$variable}. 

An example of simple personalization in use 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

Variables should begin with double curly brackets {{ followed by the name of the variable and closed with double opposite curly brackets }} as so: {{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 specific 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 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 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 HTML template, use our Rich-text editor or our Drag & drop editor.

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

5. You can find the Sending instructions at the bottom of the template's page, for which cURL, PHP, Laravel, Java, Ruby, Node, Go, and Python can be used.

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

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

• In the right-side column of the Template page

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.

1. If using Google Fonts, click + Select this style next to the font to open a side panel.

Drag & drop editor

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

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

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

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

<style>p { !important }</style>

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>

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>

1. Write the text for your email template, enclosing them in <p> tags.

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.

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>

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.

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

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

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.