Send API

One URL. One key. Mail from your domain.

The MailerZ send API is POST https://mail.mailerz.net/api/v1/send with Authorization: Bearer mz_live_YOUR_KEY. Need subject plus text or html. From must be an enabled alias you own. Bcc is not written into MIME. Header From is never rewritten. Agents that speak MCP should use /mcp instead of inventing a second key.

Key takeaways

POST /api/v1/send is the MailerZ send API. One mz_live_ key. Hosted From only.
The same gates as MCP: paid send-as, live SPF, live DKIM, enabled alias.
Idempotency-Key replays the first result for 24 hours. See Developers, pricing, and security.

Examples

Plain send

curl -X POST https://mail.mailerz.net/api/v1/send \
  -H "Authorization: Bearer mz_live_YOUR_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"from":"hello@your-domain.com","to":"user@gmail.com","subject":"Hello","text":"Plain body"}'

Same body with Idempotency-Key

curl -X POST https://mail.mailerz.net/api/v1/send \
  -H "Authorization: Bearer mz_live_YOUR_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Idempotency-Key: invoice-1042" \
  -d '{"from":"hello@your-domain.com","to":"user@gmail.com","subject":"Invoice 1042","text":"Plain body"}'

The same key within 24 hours returns the first result with idempotent: true and HTTP 200.

Fields

Field	Meaning
`status`	Always present. true = sent. false = not sent.
`message`	Always present. Plain-language result.
`error`	Only when status is false. Machine code.
`from`	Owned address. String, {email,name}, or list. Omit = first eligible alias.
`to / cc / bcc`	Same shapes. Need at least one. Bcc stays off MIME headers.
`replyTo`	Optional. Max 5. reply_to also accepted.
`subject`	Required. UTF-8, max 900.
`text / html`	Need one. Combined max ~10 MB.
`attachments`	filename, content (base64 or data URL), contentType, optional cid.
`headers`	X-* only, max 20.
`inReplyTo / references`	Threading.
`Idempotency-Key`	Header or idempotencyKey. 24 hours.

Errors

HTTP	Code	Cause
401	`API_KEY_REQUIRED`	No Bearer and no X-Api-Key
401	`API_KEY_INVALID`	Not a stored mz_live_ / mz_root_ key
403	`API_KEY_REVOKED`	Revoked on the desk
400	`SUBJECT_REQUIRED`	Empty subject
400	`NO_BODY`	Need text or html
400	`BODY_TOO_LARGE`	text+html over ~10 MB
400	`RECIPIENT_REQUIRED`	to, cc, bcc all empty
400	`TOO_MANY_RECIPIENTS`	Over 20 envelope or 5 Reply-To
400	`INVALID_RECIPIENT:to`	Bad address (suffix can be to/cc/bcc/replyTo)
400	`INVALID_FROM`	From is not a usable enabled alias
400	`PLATFORM_FROM_REQUIRED`	mz_root_ must be @mailerz.net or @mail.mailerz.net
404	`NOT_FOUND`	From not on this workspace, or catch-all *
400	`ATTACHMENT_INVALID / _LIMIT / _TOO_LARGE`	Bad or oversized files
400	`INVALID_HEADERS`	Not X-* or more than 20
403	`SEND_AS_LOCKED`	Free plan / send-as off
403	`SEND_AS_DKIM_REQUIRED`	DKIM not live
403	`SEND_AS_SPF_REQUIRED`	SPF not live
403	`DOMAIN_OUTBOUND_PAUSED`	Outbound paused
403	`PLAN_OUTGOING_LIMIT / PLAN_OUTGOING_HOURLY`	Cap hit
403	`MAIL_VIRUS / MAIL_SPAM`	Scan rejected
429	`RATE_LIMITED`	80 calls / hour

Limits

Free plan cannot send (SEND_AS_LOCKED). Paid send-as, live SPF, and live DKIM are required.
80 sends / hour / workspace and / key.
20 unique To+Cc+Bcc. Reply-To max 5. Subject max 900.
Attachments: 10 files, 7 MB each, 10 MB total. JSON body 12 MB.
MAIL_SPAM and MAIL_VIRUS mean the message was not sent.
We do not train models on customer mail. Not SOC 2. See pricing and security.

Mint the key on the desk.

Start free with one domain. After the account exists, open Developer and copy mz_live_.

Start free — one domain Open Developer