Email: Send
Send one or more emails, with optional attachments, via the Mersal API.
4 min read
Send one or more emails in a single request, with support for a custom sender name, reply-to address, scheduling, and file attachments.
Endpoint
POSThttps://mersal.it/api/email/send
Authentication
Requires your personal API key via the Api-key header (or the api_key query/body fallback). See Authentication.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
contact | array | Yes | Array of recipients. Must contain at least 1 item. |
contact.*.email | string | Yes | The recipient's email address. Must be a valid email. |
contact.*.subject | string | Yes | The email subject line. |
contact.*.message | string | Yes | The email body. HTML is supported. |
contact.*.gateway_identifier | string | No | UID of a specific email gateway to send through. If provided, it must reference an active email-channel gateway on your account. Omit to use your account's default/active email gateway. |
contact.*.sender_name | string | No | Custom display name for the sender. |
contact.*.reply_to_email | string | No | Reply-to address for the email. |
contact.*.schedule_at | string | No | Schedule delivery for a future time, format Y-m-d H:i:s. Omit to send immediately. |
attachments | array | No | Array of files to attach. Allowed types: pdf, doc, docx, xls, xlsx, csv, txt, png, jpg, jpeg, gif, zip, rar, svg, webp. Subject to your account's configured attachment limits (max file count and max size). |
Example request
curl -X POST https://mersal.it/api/email/send \
-H "Api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact": [
{
"email": "[email protected]",
"subject": "Your July invoice is ready",
"message": "<p>Hi there, your invoice for July is attached.</p>",
"sender_name": "Mersal Billing",
"reply_to_email": "[email protected]"
}
],
"attachments": []
}'<?php
$response = Http::withHeaders([
'Api-key' => 'YOUR_API_KEY',
'Content-Type' => 'application/json',
])->post('https://mersal.it/api/email/send', [
'contact' => [
[
'email' => '[email protected]',
'subject' => 'Your July invoice is ready',
'message' => '<p>Hi there, your invoice for July is attached.</p>',
'sender_name' => 'Mersal Billing',
'reply_to_email' => '[email protected]',
],
],
'attachments' => [],
]);
$data = $response->json();<?php
$payload = [
'contact' => [
[
'email' => '[email protected]',
'subject' => 'Your July invoice is ready',
'message' => '<p>Hi there, your invoice for July is attached.</p>',
'sender_name' => 'Mersal Billing',
'reply_to_email' => '[email protected]',
],
],
'attachments' => [],
];
$ch = curl_init('https://mersal.it/api/email/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Api-key: YOUR_API_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);const response = await fetch("https://mersal.it/api/email/send", {
method: "POST",
headers: {
"Api-key": process.env.MERSAL_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
contact: [
{
email: "[email protected]",
subject: "Your July invoice is ready",
message: "<p>Hi there, your invoice for July is attached.</p>",
sender_name: "Mersal Billing",
reply_to_email: "[email protected]",
},
],
attachments: [],
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://mersal.it/api/email/send",
headers={"Api-key": os.environ["MERSAL_API_KEY"]},
json={
"contact": [
{
"email": "[email protected]",
"subject": "Your July invoice is ready",
"message": "<p>Hi there, your invoice for July is attached.</p>",
"sender_name": "Mersal Billing",
"reply_to_email": "[email protected]",
}
],
"attachments": [],
},
)
data = response.json()Example response
{
"success": true,
"message": "Email queued successfully",
"data": {
"contact": [
{
"email": "[email protected]",
"status": "queued"
}
]
}
}On validation failure, Mersal returns 422:
{
"success": false,
"message": "Validation failed",
"errors": {
"contact.0.email": ["The contact.0.email must be a valid email address."]
}
}Attaching files
If you need to send attachments, submit attachments as a multipart file upload rather than an empty array. Check your account's Gateways settings for the configured max file count and max size before relying on attachments in production.
Errors
Common failure modes are a missing/invalid API key, an expired subscription, a 422 validation error on contact or attachments, or a gateway_identifier that doesn't reference an active email gateway. See Errors and Status Codes for the full reference.
Was this page helpful?