Emails
Send a single transactional email.
Send a single transactional email and get the message id back.
/v1/emailssending or fullThe email is delivered synchronously through our email provider, so the response confirms the send immediately and returns the message id. Merge variables are rendered against the matching contact when the recipient is one of your contacts — see Personalization.
Body parameters
| Field | Type | Required | Description |
|---|---|---|---|
from | string | optional | Sender address on a verified domain. Defaults to the project default. |
to | string | required | Recipient email address. |
subject | string | required | Subject line. Supports merge variables. |
html | string | required | HTML body. Supports merge variables. |
text | string | optional | Plain-text alternative sent alongside the HTML (improves deliverability). |
reply_to | string | optional | Reply-To address. No verification required. |
unsubscribe_template | none · minimal · branded · card | optional | Unsubscribe footer to append. Defaults to none. |
attachments | array | optional | File attachments. See below. Up to 10 files, 10 MB each, 25 MB total. |
Attachment object
Each entry in attachments provides the file either inline as base64
content or as a remote path URL we fetch — set exactly one.
| Field | Type | Required | Description |
|---|---|---|---|
filename | string | required | Name the recipient sees. Executable/script types are rejected. |
content | string | one of | Base64-encoded file bytes (a data: URL prefix is accepted). |
path | string | one of | http(s) URL to the file; we download and attach it. |
content_type | string | optional | MIME type. Inferred from a fetched path when omitted. |
Example request
Use the official Node.js SDK (npm install mailer123) or call the endpoint
with any HTTP client.
import { Mailer123 } from "mailer123";
const mailer = new Mailer123(process.env.MAILER123_API_KEY);
const { data, error } = await mailer.emails.send({
from: "you@yourdomain.com",
to: "customer@example.com",
subject: "Your receipt",
html: "<p>Thanks, {{name|there}}!</p>",
text: "Thanks, {{name|there}}!",
replyTo: "support@yourdomain.com",
attachments: [
{ filename: "receipt.pdf", content: "JVBERi0xLjQK..." },
{ filename: "logo.png", path: "https://yourdomain.com/logo.png" },
],
});
if (error) {
console.error(error.code, error.message);
} else {
console.log("Sent:", data.id);
}Response
HTTP/1.1 202 Accepted
{ "id": "0100018f-1a2b-3c4d-..." }Errors
validation_error (400), forbidden (403 — unverified or blocked sender),
conflict (409 — suppressed recipient), quota_exceeded (429), send_failed
(502). See the error reference.