Send Basic Email
Send a POST request to the API endpoint with a JSON payload to create and send an email from scratch.
Send a POST request to the API endpoint with a JSON payload to create and send an email from scratch. Your request must include the sender's email address, recipient's email address, subject line, and the email content in either plain text, HTML, or both.
Request Body
fromobjectrequiredThis can be anything @yourdomain.com, but it must be a verified domain in your Maileroo account. Must be an EmailObject.
toarray | objectrequiredPrimary recipient(s). Can be a single EmailObject or an array of EmailObject.
ccarray | objectoptionalCarbon copy recipients. Can be a single EmailObject or an array of EmailObject.
bccarray | objectoptionalBlind carbon copy recipients. Can be a single EmailObject or an array of EmailObject.
reply_toarray | objectoptionalReply-to email addresses. Can be a single EmailObject or an array of EmailObject.
subjectstringrequiredThe subject line of the email. Must not exceed 255 characters.
htmlstringoptionalEmail body in HTML format. Either html or plain is required.
plainstringoptionalEmail body in plain text format. Either html or plain is required. If unspecified, a plain text version will be automatically generated from the HTML content. You can override this by providing your own plain text content or setting it to an empty string.
trackingbooleanoptionalEnable or disable open/click tracking for the email. If not specified, defaults to account settings.
tagsobject (map)optionalCustom 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.
headersobject (map)optionalCustom 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.
attachmentsarrayoptionalWhen specified, it should contain an array of AttachmentObject.
scheduled_atstringoptionalIf you want to schedule the email for future delivery, specify the time in RFC 3339 format (e.g., 2024-08-05T11:52:01.858Z). You can also use natural language like tomorrow at 2pm, in 2 hours, etc. relative to the server time.
reference_idstringoptionalUnique 24-char hex ID for tracking. Auto-generated if omitted. Refer to Reference ID for more details.
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
Content-Type: application/json
{
"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"
},
"subject": "Welcome to Maileroo: Your Complete Email Delivery Solution",
"html": "<h1>Welcome!</h1><p>This is a <strong>test email</strong> with HTML formatting.</p><img src='cid:logo123' />",
"plain": "Welcome! This is a test email with plain text content.",
"tracking": true,
"tags": {
"campaign": "welcome-series",
"user_id": "12345"
},
"headers": {
"X-Custom-Header": "CustomValue",
"X-Trace-ID": "trace-abc123xyz"
},
"attachments": [
{
"file_name": "document.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
}
],
"scheduled_at": "2025-08-01T15:30:00Z",
"reference_id": "5f2b4c9d8a7e4f3b2c1d9e8f"
}Sample Response
{
"success": true,
"message": "The email has been scheduled for delivery.",
"data": {
"reference_id": "c843204e3af03193bd14f339"
}
}