Send Bulk Emails
In addition to sending individual emails, Maileroo allows you to send bulk emails by sending a POST request with a JSON payload. You can either supply a template ID or provide the full email content with full templating functionality. This is particularly useful for sending newsletters, marketing campaigns, or any other type of mass communication.
Endpoint
POST https://smtp.maileroo.com/api/v2/emails/bulk
Request Body
subject string required
The email subject line, limited to 255 characters. It also supports simple, dynamic variables from template data (for example, {{ first_name }}).
messages array required
An array of MesssageObject items, where each item represents a single email to be sent. Each email can have its own from, to, cc, bcc, reply_to, reference_id and template_data. The maximum number of items in the messages array is 500.
template_id integer
You must include either plain, html, or template_id in the request body. If using template_id, it must reference a valid template in your Maileroo account.
Required when plain and html are not provided.
plain string
Email body in plain text format. Either html or plain is required. Templating support is available in plain text emails, allowing you to use variables and expressions.
Required when html or template_id are not provided.
html string
Email body in HTML format. Either html or plain is required. Templating support is available in HTML emails, allowing you to use variables and expressions.
Required when plain or template_id are not provided.
tracking boolean
Enable or disable open/click tracking for the email. If not specified, defaults to account settings.
tags object (map)
Custom tags for categorizing the email. Accepts a flexible object (map), allowing you to define any key-value pairs.
Maximum key length is 128 characters, and maximum value length is 768 characters.
headers object (map)
Custom email headers (e.g., X-Custom-Header). Accepts a flexible object (map), allowing you to define any key-value pairs.
Maximum key length is 128 characters, and maximum value length is 768 characters. Supports simple, dynamic variables from template data (e.g., {{ campaign_id }}).
attachments array
When specified, it should contain an array of AttachmentObject.
MessageObject
| Field | Type | Required | Description |
|---|---|---|---|
from | object | required | The sender's email address. Must be an EmailObject. |
to | object/array | required | Can be a single EmailObject or an array of EmailObject. |
cc | object/array | optional | Can be a single EmailObject or an array of EmailObject. |
bcc | object/array | optional | Can be a single EmailObject or an array of EmailObject. |
reply_to | object/array | optional | Can be a single EmailObject or an array of EmailObject. |
reference_id | string | optional | A unique identifier for tracking the email. Must be a valid 24-character hexadecimal string. |
template_data | object | optional | Accepts a flexible key-value object (supports nested objects/arrays) mapping keys to template variables. Values may be strings, numbers, booleans, objects, or arrays. |
EmailObject
| Field | Type | Required | Description |
|---|---|---|---|
address | string | required | Email address |
display_name | string | optional | Display name for the email. |
AttachmentObject
| Field | Type | Required | Description |
|---|---|---|---|
file_name | string | required | Name of the file to attach. |
content_type | string | optional | MIME type of the file. If not specified, we'll try to guess it, otherwise defaults to application/octet-stream. |
content | string | required | Base64-encoded content of the file. |
inline | bool | optional | If true, the attachment will be treated as an inline image. Defaults to false. This is useful for embedding images in HTML emails. |
Sample Request
The following is a sample request to send an email.
POST https://smtp.maileroo.com/api/v2/emails/bulk
Content-Type: application/json
{
"subject": "Welcome {{ first_name }} - Your Exclusive Offer Awaits!",
"messages": [
{
"from": {
"address": "[email protected]",
"display_name": "John Doe"
},
"to": [
{
"address": "[email protected]",
"display_name": "Jane Smith"
},
{
"address": "[email protected]"
}
],
"cc": {
"address": "[email protected]",
"display_name": "CC Person"
},
"bcc": [
{
"address": "[email protected]"
},
{
"address": "[email protected]",
"display_name": "Hidden Two"
}
],
"reply_to": {
"address": "[email protected]",
"display_name": "Support Team"
},
"reference_id": "5f2b4c9d8a7e4f3b2c1d9e8f",
"template_data": {
"first_name": "Jane",
"last_name": "Smith",
"discount_code": "WELCOME50",
"account_info": {
"plan": "Enterprise",
"region": "APAC"
},
"features": [
"SMTP Relay",
"Email API",
"Templates"
]
}
},
{
"from": {
"address": "[email protected]",
"display_name": "Offers Team"
},
"to": [
{
"address": "[email protected]",
"display_name": "Bob Johnson"
}
],
"reference_id": "9f1c3b8a4d2e7f3c1a0b9d8e",
"template_data": {
"first_name": "Bob",
"last_name": "Johnson",
"discount_code": "SUMMER25",
"preferences": {
"newsletter": true,
"promotions": false
}
}
}
],
"template_id": 2048,
"plain": "Hi {{ first_name }},\n\nThanks for joining us! Use your code {{ discount_code }} to get started.",
"html": "<h1>Hi {{ first_name }}</h1><p>Thanks for joining us! Use your code <strong>{{ discount_code }}</strong> to get started.</p>",
"tracking": true,
"tags": {
"campaign": "welcome-series",
"region": "APAC",
"batch": "batch-1"
},
"headers": {
"X-Campaign-ID": "{{ campaign }}",
"X-Custom-Header": "CustomValue"
},
"attachments": [
{
"file_name": "brochure.pdf",
"content_type": "application/pdf",
"content": "JVBERi0xLjUKJYGBgYEKC... (truncated base64)",
"inline": false
},
{
"file_name": "logo.png",
"content_type": "image/png",
"content": "iVBORw0KGgoAAAANSUhEUgAA... (truncated base64)",
"inline": true
}
]
}
Sample Response
{
"success": true,
"message": "The email has been scheduled for delivery.",
"data": {
"reference_ids": [
"8d6bda8b298ac128125d9d30",
"16ade7e1d359adc9c0bb1315"
]
}
}