Sending an 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

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"
          }
        ]
      }
    ]
  }
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$recipients = [
    new Recipient('your@client.com', 'Your Client'),
];

$emailParams = (new EmailParams())
    ->setFrom('your@domain.com')
    ->setFromName('Your Name')
    ->setRecipients($recipients)
    ->setSubject('Subject')
    ->setHtml('This is the HTML content')
    ->setText('This is the text content')
    ->setReplyTo('reply to')
    ->setReplyToName('reply to name');

$mailersend->email->send($emailParams);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const sentFrom = new Sender("you@yourdomain.com", "Your name");

const recipients = [
  new Recipient("your@client.com", "Your Client")
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setReplyTo(sentFrom)
  .setSubject("This is a Subject")
  .setHtml("<strong>This is the HTML content</strong>")
  .setText("This is the text content");

await mailerSend.email.send(emailParams);

More examplesopen in new window

from mailersend import emails

api_key = "API key here"

mailer = emails.NewEmail(api_key)

# define an empty dict to populate with mail values
mail_body = {}

mail_from = {
    "name": "Your Name",
    "email": "your@domain.com",
}

recipients = [
    {
        "name": "Your Client",
        "email": "your@client.com",
    }
]

reply_to = [
    {
        "name": "Name",
        "email": "reply@domain.com",
    }
]

mailer.set_mail_from(mail_from, mail_body)
mailer.set_mail_to(recipients, mail_body)
mailer.set_subject("Hello!", mail_body)
mailer.set_html_content("This is the HTML content", mail_body)
mailer.set_plaintext_content("This is the text content", mail_body)
mailer.set_reply_to(reply_to, mail_body)

# using print() will also return status code and data
mailer.send(mail_body)

More examplesopen in new window

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	subject := "Subject"
	text := "This is the text content"
	html := "<p>This is the HTML content</p>"

	from := mailersend.From{
		Name:  "Your Name",
		Email: "your@domain.com",
	}

	recipients := []mailersend.Recipient{
		{
			Name:  "Your Client",
			Email: "your@client.com",
		},
	}

	// Send in 5 minute
	sendAt := time.Now().Add(time.Minute * 5).Unix()

	tags := []string{"foo", "bar"}

	message := ms.Email.NewMessage()

	message.SetFrom(from)
	message.SetRecipients(recipients)
	message.SetSubject(subject)
	message.SetHTML(html)
	message.SetText(text)
	message.SetTags(tags)
	message.SetSendAt(sendAt)
	message.SetInReplyTo("client-id")

	res, _ := ms.Email.Send(ctx, message)

	fmt.Printf(res.Header.Get("X-Message-Id"))

}

More examplesopen in new window

import com.mailersend.sdk.Email;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;

public void sendEmail() {

    Email email = new Email();

    email.setFrom("name", "your email");
    email.addRecipient("name", "your@recipient.com");

    // you can also add multiple recipients by calling addRecipient again
    email.addRecipient("name 2", "your@recipient2.com");

    // there's also a recipient object you can use
    Recipient recipient = new Recipient("name", "your@recipient3.com");
    email.addRecipient(recipient);
    
    email.setSubject("Email subject");

    email.setPlain("This is the text content");
    email.setHtml("<p>This is the HTML content</p>");

    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        MailerSendResponse response = ms.send(email);
        System.out.println(response.messageId);
    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

# Intialize the email class
ms_email = Mailersend::Email.new

# Add parameters
ms_email.add_recipients("email" => "ron@parksandrec.com", "name" => "Ron")
ms_email.add_recipients("email" => "leslie@parksandrec.com", "name" => "Leslie")
ms_email.add_from("email" => "april@parksandrec.com", "name" => "April")
ms_email.add_subject("Time")
ms_email.add_text("Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.")
ms_email.add_html("<b>Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.</b>")

# Send the email
ms_email.send

More examplesopen in new window

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 or a subdomain from 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 25MB. After decoding Base64Base64 encoded content of the attachment.
attachments.*.dispositionstringyesMust be one of the attachment types: inline, attachmentUse inline to make it accessible for content. use attachment to normal attachments
attachments.*.filenamestringyes
attachments.*.idstringnoCan be used in content as <img src="cid:*"/>. Must also set attachments.*.disposition as inline.
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.
in_reply_tostringnoAlphanumeric which can contain _, -, @ and ..
settingsobjectno
settings.*booleanyesCan only contain the keys: track_clicks, track_opens and track_content and a boolean value of true or false.

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]

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 - Validation 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 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

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"
            }
          ]
        }
      ]
    }
  ]
use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;

$mailersend = new MailerSend(['api_key' => 'key']);

$recipients = [
    new Recipient('your@client.com', 'Your Client'),
];

$bulkEmailParams = [];

$bulkEmailParams[] = (new EmailParams())
    ->setFrom('your@domain.com')
    ->setFromName('Your Name')
    ->setRecipients($recipients)
    ->setSubject('Subject')
    ->setHtml('This is the HTML content')
    ->setText('This is the text content');

$bulkEmailParams[] = (new EmailParams())
    ->setFrom('your@domain.com')
    ->setFromName('Your Name')
    ->setRecipients($recipients)
    ->setSubject('Subject')
    ->setHtml('This is the HTML content')
    ->setText('This is the text content');

$mailersend->bulkEmail->send($bulkEmailParams);

More examplesopen in new window

import 'dotenv/config';
import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const sentFrom = new Sender("your@yourdomain.com", "Your name");

const bulkEmails = [];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo([
    new Recipient("your@client.com", "Your Client")
  ])
  .setSubject("This is a Subject")
  .setHtml("<strong>This is the HTML content</strong>")
  .setText("This is the text content");

bulkEmails.push(emailParams);

const emailParams2 = new EmailParams()
  .setFrom(sentFrom)
  .setTo([
    new Recipient("your_2@client.com", "Your Client 2")
  ])
  .setSubject("This is a Subject 2")
  .setHtml("<strong>This is the HTML content 2</strong>")
  .setText("This is the text content 2");

bulkEmails.push(emailParams2);

await mailerSend.email.sendBulk(bulkEmails);

More examplesopen in new window

from mailersend import emails

api_key = "API key here"

mailer = emails.NewEmail(api_key)

mail_list = [
  {
    "from": {
      "email": "your@domain.com",
      "name": "Your Name"
    },
    "to": [
      {
        "email": "your@client.com",
        "name": "Your Client"
      }
    ],
    "subject": "Subject",
    "text": "This is the text content",
    "html": "<p>This is the HTML content</p>",
  },
  {
    "from": {
      "email": "your@domain.com",
      "name": "Your Name"
    },
    "to": [
      {
        "email": "your@client.com",
        "name": "Your Client"
      }
    ],
    "subject": "Subject",
    "text": "This is the text content",
    "html": "<p>This is the HTML content</p>",
  }
]

print(mailer.send_bulk(mail_list))

More examplesopen in new window

package main

import (
    "context"
	"time"
	"log"
	"fmt"
	
    "github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)
	
	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	subject := "Subject"
	text := "This is the text content"
	html := "<p>This is the HTML content</p>"

	from := mailersend.From{
		Name:  "Your Name",
		Email: "your@domain.com",
	}

	recipients := []mailersend.Recipient{
		{
			Name:  "Your Client",
			Email: "your@client.com",
		},
	}

	var messages []*mailersend.Message
	
	for i := range [2]int{} {
		msg := &mailersend.Message{
			From:       from,
			Recipients: recipients,
			Subject:    fmt.Sprintf("%s %v", subject, i),
			Text:       text,
			HTML:       html,
		}
		messages = append(messages, msg)
	}
	
	_, _, err := ms.BulkEmail.Send(ctx, messages)
	if err != nil {
		log.Fatal(err)
	}

}

More examplesopen in new window

import com.mailersend.sdk.emails.Email;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;

public void sendBulkEmails() {

    Email email1 = new Email();

    email1.setFrom("name", "your email");
    email1.addRecipient("name", "your@first-recipient.com");
   
    email1.setSubject("Email subject 1");

    email1.setPlain("This is the text content for the first email");
    email1.setHtml("<p>This is the HTML content for the first email</p>");

    Email email2 = new Email();

    email2.setFrom("name", "your email");
    email2.addRecipient("name", "your@second-recipient.com");
   
    email2.setSubject("Email subject 2");

    email2.setPlain("This is the text content for the second email");
    email2.setHtml("<p>This is the HTML content for the second email</p>");

    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        String bulkSendId = ms.emails().bulkSend(new Email[] { email1, email2 });

        // you can use the bulkSendId to get the status of the emails
        System.out.println(bulkSendId);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_bulk_email = Mailersend::BulkEmail.new

ms_bulk_email.messages = [
    {
        'from' => {"email" => "april@parksandrec.com", "name" => "April"},
        'to' => [{"email" => "ron@parksandrec.com", "name" => "Ron"}],
        'subject' => "Time",
        'text' => "Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.",
        'html' => "<b>Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.</b>",
      },
      {
        'from' => {"email" => "april@parksandrec.com", "name" => "April"},
        'to' => [{"email" => "leslie@parksandrec.com", "name" => "Leslie"}],
        'subject' => "Lorem Ipsum",
        'text' => "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
        'html' => "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
      }
]

ms_bulk_email.send

More examplesopen in new window

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
{
  "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

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}

Request parameters

URL parameterTypeRequiredLimitationsDetails
bulk_email_idstringyes
use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->bulkEmail->getStatus('bulk_email_id');

More examplesopen in new window

import 'dotenv/config';
import { MailerSend } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

mailerSend.email.getBulkStatus('bulk_email_id') // bulk email Id e.g 63af1fdb790d97105a090001
  .then((response) => {
    console.log(response.body);
  });

More examplesopen in new window

from mailersend import emails

api_key = "API key here"

mailer = emails.NewEmail(api_key)

print(mailer.get_bulk_status_by_id("bulk-email-id"))

More examplesopen in new window

package main

import (
	"context"
	"time"
	"log"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.Background()
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	
	_, _, err := ms.BulkEmail.Status(ctx, "bulk-email-id")
	if err != nil {
		log.Fatal(err)
	}
	
}

More examplesopen in new window

import com.mailersend.sdk.emails.Email;
import com.mailersend.sdk.emails.BulkSendStatus;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;

public void getBulkEmailsStatus() {

    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        BulkSendStatus status = ms.emails().bulkSendStatus("bulk send id");

        System.out.println(status.state);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

More examplesopen in new window

require "mailersend-ruby"

ms_bulk_email = Mailersend::BulkEmail.new
ms_bulk_email.get_bulk_status(bulk_email_id: 'yourbulkemailid')

More examplesopen in new window

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: