Transactional email API
One REST call for every email your product sends
Send receipts, password resets, alerts and account notices through POST /v1/transactional/send. MailLand checks the request, signs each message with your domain's DKIM key, hands it to its mail servers and reports what happened to it. The servers run at Hetzner in Germany.
curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: ml_pet_..." \
-H "X-Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "[email protected]", "name": "Your App" },
"to": [{ "email": "[email protected]", "name": "Jane" }],
"subject": "Your receipt for order 1042",
"htmlContent": "<p>Thanks, Jane. Your payment was received.</p>",
"textContent": "Thanks, Jane. Your payment was received.",
"tags": ["receipt"]
}'What happens after you call the API
Four stages, each one visible to you in the response, the message log or a webhook.
Checked
The API checks the sender domain, your key's scope and limits, and each recipient. Suppressed addresses are refused and listed in rejectedRecipients; with typo and disposable-domain protection turned on, those are listed too, with a suggested correction for a typo.
Queued
Each accepted message is written to MailLand's database before the API answers 202 Accepted, then handed to the delivery queue. The response carries the job ID, one message ID per recipient and the time it was queued; a scheduled send returns a schedule ID instead.
Signed and sent
Every recipient gets a separate copy with its own message ID and no visible Cc, signed with your domain's DKIM key and sent from MailLand's shared sending IP addresses.
Reported
Delivered, deferred, bounced, failed and complaint events reach your webhook and the message log. Each event carries a status version, so you can apply them in the right order.
What the API gives you
Each of these is a field, a header or an endpoint, documented with examples.
Stored templates with variables
Keep HTML and text templates in MailLand and fill {{placeholders}} per recipient. If a variable has no value, the message is not sent with the raw placeholder in it: the API answers 422 and names what is missing.
Idempotency keys
Send an X-Idempotency-Key header with a send. A retry with the same key within 24 hours returns the original response and sends nothing, so retrying after a network timeout does not send a second copy.
Scheduled sends
Add scheduledAt to send up to 7 days ahead. List, reschedule or cancel a scheduled message through the API before it goes out.
Attachments and inline images
Attach up to 10 files and 10 MiB per message, including inline images that your HTML references by Content-ID.
Tags and custom headers
Tag messages to filter them in analytics, logs and webhooks, add your own headers, and set a reply-to address per message.
Pre-flight check
GET /v1/transactional/send/check tells you whether your account can send right now, with its current rate-limit usage and monthly quota. It does not check a particular sender or recipient.
Sandbox keys
A sandbox key accepts and records requests without delivering them, or delivers only to an allow-list you control, so test mail reaches only the addresses you choose.
Keys you can scope
Limit each key to one stream, to selected sending domains, to an IP allow-list, to per-minute, hourly and daily limits and to an expiry date. Rotate it from the panel or the API.
Know what happened to every message
Accepting a request is only half of the job. MailLand tells you what came after.
Signed webhooks
Subscribe to delivered, deferred, bounced, failed and complained events. Every request is signed with HMAC-SHA256 in the X-MLND-Signature header and retried when your endpoint fails.
Message log
Look up any message by its ID and see each event in its history. Logs are kept for 30, 90 or 180 days, depending on your plan.
Automatic suppression
Hard bounces and complaints go on your suppression list automatically, and later sends to those addresses are refused before they leave.
A v1 that only grows
Version 1 of the API is additive only: new fields and events may appear, but nothing is removed and nothing changes meaning. A breaking change ships as /v2, announced at least 180 days ahead, and /v1 keeps running alongside it for 180 days.
Plain HTTPS, any language
MailLand has no SDK yet. The API is JSON over HTTPS with an X-API-Key header, and the documentation, available in seven languages, shows each request in curl, JavaScript, Node.js, Python, PHP, C#, Java and Go.
Hosted in the EU
MailLand's servers run at Hetzner in Germany, mainly in Nuremberg, and an encrypted backup copy is kept in Warsaw, Poland. A few sub-processors, such as Cloudflare and Stripe, may process limited data outside the EU under the EU Standard Contractual Clauses. The DPA lists each one.
Read the DPAQuestions about the transactional email API
Is there a free plan?
Yes. The Free plan includes 1,000 emails a month at no cost, with the same REST API and SMTP relay as the paid plans. No credit card is needed to start.
Do you have SDKs?
Not yet. The API is JSON over HTTPS, so any HTTP client works. The documentation has copy-paste examples in curl, JavaScript, Node.js, Python, PHP, C#, Java and Go.
How do I make sure a retry does not send the email twice?
Send an X-Idempotency-Key header (or the idempotencyKey field) with POST /v1/transactional/send or send-batch. A retry with the same key within 24 hours returns the original response and sends nothing. These two endpoints are the only ones that accept a key.
Can one request go to many recipients?
A transactional request takes up to 5 recipients, and each one receives a separate copy. For bulk mail, use a marketing key with POST /v1/transactional/send-batch, which takes up to 10,000 recipients per request.
What happens when a message bounces?
A hard bounce or complaint adds the address to your suppression list and is sent to your webhook as an event. Later sends to that address are refused and listed in rejectedRecipients.
What are the sending limits?
Each plan sets a monthly volume and a per-minute sending rate, shown on the pricing page. A key can carry its own lower limits. Over a limit, the API answers 429 with a Retry-After header.
Send your first email today
Create a free account, verify your domain and call the API. 1,000 emails a month are free.