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>",
    "personalization": [
      {
        "email": "john@mailersend.com",
        "data": {
          "company": "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 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 or a subdomain from 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 *	Max 998	Not required if `template_id` is present and template has default subject set.
`text`	`string`	yes *	Max size of 2 MB.	Email represented in a text (`text/plain`) format. * Only required if there's no `html` or `template_id` present.
`html`	`string`	yes *	Max size of 2 MB.	Email represented in HTML (`text/html`) format. * Only required if there's no `text` or `template_id` present.
`attachments`	`object[]`	no
`attachments.*.content`	`string`	yes	Max size of 25MB. After decoding Base64	Base64 encoded content of the attachment.
`attachments.*.disposition`	`string`	yes	Must be one of the attachment types: `inline`, `attachment`	Use `inline` to make it accessible for content. use `attachment` to normal attachments
`attachments.*.filename`	`string`	yes
`attachments.*.id`	`string`	no		Can be used in content as `<img src="cid:"/>`. Must also set `attachments..disposition` as `inline`.
`template_id`	`string`	yes *		* Only required if there's no `text` or `html` present.
`tags`	`string[]`	no		Limit is max 5 tags. If the template used already has tags, then the request will override them.
`personalization`	`object[]`	no		Allows using personalization in `{{var}}` syntax. Can be used in the `subject`, `html`, `text` fields. Read more about advanced personalization.
`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.
`precedence_bulk`	`boolean`	no		This parameter will override domain's advanced settings
`send_at`	`integer`	no	min: `now`, max: `now + 72hours`	Has 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_to`	`string`	no		Alphanumeric which can contain `_`, `-`, `@` and `.`.
`settings`	`object`	no
`settings.*`	`boolean`	yes		Can only contain the keys: `track_clicks`, `track_opens` and `track_content` and a boolean value of `true` or `false`.
`headers`	`object[]`	no		Please note that this feature is available to Enterprise accounts only
`headers.*.name`	`string`	yes	Must be alphanumeric which can contain `-`
`headers.*.value`	`string`	yes

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

Note

If a scheduled email is sent with a template, and that template is deleted before the sending is triggered, the scheduled email will not be sent.

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 domain must be verified in your account to send emails. #MS42207"
    ]
  }
}

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 encrypted emails

You can use MailerSend to send encrypted messages using S/MIME or PGP. The sender encrypts messages that use these protocols. Their contents can only be viewed by recipients with the private keys required to decrypt the messages.

MailerSend supports the following MIME types, which you can use to send S/MIME encrypted emails:

application/pkcs7-mime
application/pkcs7-signature
application/x-pkcs7-mime
application/x-pkcs7-signature

MailerSend also supports the following MIME types, which you can use to send PGP-encrypted emails:

application/pgp-encrypted
application/pgp-keys
application/pgp-signature

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>",
      "personalization": [
        {
          "email": "john@mailersend.com",
          "data": {
            "company": "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>",
      "personalization": [
        {
          "email": "jane@mailersend.com",
          "data": {
            "company": "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 parameter	Type	Required	Limitations	Details
`*`	`object[]`	yes	Must be an array.	Array of email 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

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 parameter	Type	Required	Limitations	Details
`bulk_email_id`	`string`	yes

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

# Sending an Email

# Send an email

# Request Body

# Request parameters

# Supported file types

# Responses

# Sending queued

# Sending paused

# Validation error

# Validation warning

# Send encrypted emails

# Send bulk emails

# Request Body

# Request parameters

# Limitations

# Responses

# Errors

# Validation errors

# Suppression errors

# Get bulk email status

# Request parameters

# Responses

# Valid

# Invalid

Sending an Email

Send an email

Request Body

Request parameters

Supported file types

Responses

Sending queued

Sending paused

Validation error

Validation warning

Send encrypted emails

Send bulk emails

Request Body

Request parameters

Limitations

Responses

Errors

Validation errors

Suppression errors

Get bulk email status

Request parameters

Responses

Valid

Invalid