A send is one POST to https://api.mails.ai/v1/messages with a bearer key. from, to and subject are required, plus at least one of body_text or body_html.
Idempotency
Send an Idempotency-Key header on every send. If the same key arrives twice — a retry, a crashed worker, a duplicated queue message — the second request returns the original message instead of mailing the recipient twice. It costs you one header and removes a whole class of incident.
What comes back
201 and the full message object: its id (msg_...), the address it actually sent as, the routing pool it took, its classifier score, and status. Status moves sent → delivered on its own as the receiving side confirms; bounced and complained are terminal.
Useful optional fields
reply_to— where replies should land if not the sending agent.cc/bcc— arrays of addresses.tags— your own labels, returned on every event for that message so you can correlate.scheduled_at— hold the send until a timestamp (see drafts and scheduling).
Every field, every endpoint and a live Try-it console are in the interactive API reference.
Open the API reference