Messages

Send a batch of messages

Requires scope: send. Sends up to 100 messages in one request. Per-message failures are returned inline in data[] and do not fail the batch; the HTTP status is still 201. Each failure is the error a single send would answer: a message a send limit refused carries resets_at and retry_after_seconds, one the email service would not take for now (503 upstream_unavailable) retry_after_seconds, and a plan refusal upgrade_url. With an Idempotency-Key, a batch in which no message was stored and no mail went out frees the key, so sending it again with the same key sends it; any other batch's answer is kept on the key. A scheduled message is its result once stored, even if announcing it then fails: with a key the batch answers that error, and the retry with the same key gets the batch (201) and raises the message.scheduled. A batch cannot send attachments: an item carrying attachments refuses the whole batch with 422 invalid_field (param attachments), so send that message on its own with POST /v1/messages.

post/v1/messages/batch

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/messages/batch
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Replays the stored response for a repeated key (kept 24 hours), so a retried request never double-sends; the replay carries Idempotent-Replay: true. An error is kept on the key only once the mail has gone out, so a replayed error means it was sent. Once a scheduled send is stored, a failure after that keeps the message's answer on the key instead: the retry answers with the message (201) and raises its message.scheduled if the first request did not. After a failure before either, the same key sends again, as it does after a batch that stored no message and sent no mail.

Request body

agentstring

Which agent sends this message: its name or agt_ id. Optional, as on POST /v1/messages: leave it out and from names the agent, or the workspace's single agent sends. A key tied to one agent always sends as that agent and may leave this out. Required only when the workspace has several agents and from names none of them; without it, that message fails with missing_field. In a workspace with no active or paused agent, the first one is created when the key may create agents (the manage scope); otherwise that message fails with insufficient_scope. An unknown agent fails only that message, with agent_not_found (agent_archived for an archived one), and a key tied to one agent fails it with insufficient_scope for any other, named here or in from.

fromstring

The sender you want, as on POST /v1/messages. Without agent, billing, billing@acme.com and Acme <billing@acme.com> all mean the agent called billing, and never a different agent. If there is none, it is created when the key may create agents (the manage scope) and your plan has room; otherwise only that message fails, with insufficient_scope or plan_limit_exceeded. Beside agent, only its display name is used: agent decides the sender. Either way a display name in it goes on the From line, a scheduled item's too. The address that sent comes back as from on the message's result.

ccstring[]

Addresses to copy, up to 50. Every recipient sees them.

bccstring[]

Addresses to blind-copy, up to 50. They receive the message but appear in none of its headers.

subjectstring required

Subject line, 1 to 998 characters.

body_textstring

Plain-text body, up to 1,000,000 characters. At least one of body_text and body_html is required, or their aliases text and html.

body_htmlstring

HTML body, up to 1,000,000 characters. With body_text as well, the email carries a plain-text part and an HTML part.

htmlstring

Alias of body_html: used when body_html is left out, ignored when both are sent.

textstring

Alias of body_text: used when body_text is left out, ignored when both are sent.

reply_tostring email

The address replies should go to. Left out, replies go to the agent's receiving_address.

in_reply_to_message_idstring

Id of the message this one answers (msg_… or rcv_…), named in the email's In-Reply-To header. The message joins its thread when the same agent sent or received it. Left out, it starts a new thread.

referencesstring[]

Message-IDs for the References header. Write one from another system with its angle brackets (<…>); a value without them is read as a mails.ai message id.

metadataobject

Your own key-value strings, kept with the message and returned by GET /v1/messages/{id}; they are not part of the email. Keys up to 64 characters, values up to 500.

scheduled_atstring date-time

Send this message at this time instead of now: an ISO 8601 UTC time ending in Z. A time in the past sends at once.

list_unsubscribeboolean

Opt in to RFC 8058 one-click unsubscribe: the message carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers, so the recipient's mail app shows an Unsubscribe button. One click suppresses the address for your whole workspace: every later send to it from any of your agents is refused with recipient_suppressed until you allowlist it (POST /v1/suppression/allow). Turn it on for newsletters, digests and other recurring mail. Leave it off (the default) for password resets, sign-in links, receipts and anything else the recipient must keep receiving. Needs exactly one to recipient and no cc or bcc.

Response

Per-message results (success or error objects) plus the submitted batch size.

batch_sizeinteger required

How many messages the request held; data has one entry for each.

Changes

No recorded changes to this operation across all 1 revision of this API.