Knowledge base

Schedule bulk emails with the bulk endpoint

Using MailerSend’s simple API and bulk email endpoint, you can schedule multiple emails from a single endpoint, and check their status after sending. 

A bulk email endpoint allows you to send a large number of personalized emails to multiple recipients through a single API call. This process improves the overall efficiency of your email campaigns by consolidating multiple emails into a single HTTP request. With MailerSend’s dynamic email templates and custom variables, you can easily personalize each email for individual recipients, even when sending in bulk. 

Why use a bulk email endpoint?

Using a bulk email endpoint offers several advantages for businesses and individuals looking to send large volumes of emails. Some of the key benefits include:

  • Faster processing: When you send multiple emails separately, each email requires its own API call. Combining emails into a single HTTP request reduces the number of API calls, resulting in less server load, quicker delivery, and improved performance

  • Quota conservation: A bulk email endpoint helps you preserve your daily request quota by minimizing the number of individual API calls required to send emails 

  • Scalability: Bulk email endpoints are designed to handle large volumes of emails, making them ideal for businesses experiencing growth or with varying email needs. This scalability ensures you can continue to deliver high-quality email campaigns as your business expands

Use Cases

Bulk email endpoints are widely used to send timely notifications such as policy updates, emergency alerts, event reminders, and more. Some common ways for utilizing bulk endpoints are:

  • E-Commerce: Use bulk endpoints to send order confirmations, shipping updates, and other transactional emails to customers who have made a purchase. Send automated reminders such as back in stock alerts, helping to drive engagement and increase sales

  • Product Updates: Businesses can use MailerSend’s bulk email endpoints to send important notifications about updates to your app, changes to the terms of service, and revisions to pricing and subscriptions

  • Surveys and feedback requests: Take advantage of email surveys and send out bulk campaigns requesting customer feedback or asking recipients to participate in surveys to gather valuable insights

  • Security alerts: Let users know about general security updates and alerts as well as potential security issues or breaches with their account

How to send batch emails in MailerSend

Note: If you're on a Free or Premium plan, you can include 500 individual email objects in a single request, each containing up to 50 TO recipients, 10 CC, and 10 BCC, for a total of 35,000 emails. Otherwise, you are limited to 5 individual email objects.

Prepare your email list: Compile a list of recipients you want to target with your bulk email campaign. This list should include the email addresses and any other relevant data needed for personalization, such as names, locations, or other custom variables.

Create a dynamic email template: Design an email template that includes your custom variables, so you can dynamically insert unique information for each recipient in your bulk email.

To send a bulk email:

  1.  Use one of our MailerSend SDKs and the code examples provided in the developers documentation, or copy paste the JSON payload below. 

  2. Make sure you added your API token and all the variables in the template. 

The payload should contain an array of email objects, with each object representing an individual email in the bulk email campaign. For example:

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;

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

$recipients = [
    new Recipient('', 'Your Client'),

$bulkEmailParams = [];

$bulkEmailParams[] = (new EmailParams())
    ->setFromName('Your Name')
    ->setHtml('This is the HTML content')
    ->setText('This is the text content');

$bulkEmailParams[] = (new EmailParams())
    ->setFromName('Your Name')
    ->setHtml('This is the HTML content')
    ->setText('This is the text content');


After sending the request, you'll receive a response with a status code and, if successful, a bulkemailid. This ID can be used to continuously query the status of your bulk email. If there are validation errors or other issues, you can check the response details.

To ensure fast deliveries, bulk emails are dispatched asynchronously without waiting for an API response. Validation of these emails is also done post-request. 

Bulk email status

To use the Get bulk email status API call to get the bulk email information like validation errors, failed emails, and more:

  1. Set the HTTP method and endpoint: Use the GET method and the provided endpoint URL, replacing {bulkemailid} with the ID of the bulk email you want to check:{bulkemailid}.

  2. Add your API key for authentication in the request headers. 

  3. Send the request. 

Here is an example using cURL:

curl -X GET "{bulkemailid}" \ -H "Authorization: Bearer {yourapikey}

After sending the request, you'll receive a response with a status code and, if successful, a JSON payload containing information about the bulk email status. This information includes:

  • id: The bulk email ID

  • state: The current state of the bulk email (e.g., "completed")

  • totalrecipientscount: The total number of recipients

  • suppressedrecipientscount: The number of suppressed recipients

  • suppressed_recipients: An array of suppressed recipient details, if any

  • validationerrorscount: The number of validation errors

  • validation_errors: An array of validation errors, if any

  • messages_id: An array of message IDs

  • created_at: The timestamp when the bulk email was created

  • updated_at: The timestamp when the bulk email was last updated

If the response returns a 404 Not Found status code, it means the bulkemailid provided is invalid or does not exist. In this case, verify the bulkemailid and try again.