HTTP API
POST https://api.mailway.net/v1/send # productionPOST https://api.mailway.dev/v1/send # sandbox — stored, never auto-forwardedThe machine-readable contract is published at
mailway.net/openapi.yaml (OpenAPI 3.1) —
every shape on this page, code-verified by the API’s own test suite so it
can’t drift. Generate a typed client from it, import it into Postman, or
hand it to a coding agent.
Authentication
Section titled “Authentication”Authorization: Bearer mw_live_… # production keys — accepted only on api.mailway.netAuthorization: Bearer mw_test_… # test keys — drive the sandboxKeys are created per-project in the console (the project’s Access section) and shown once — the key is the project selection, so there’s no project field in the request body. Full details (host binding, storage, rotation): Authentication & API keys.
Send a message
Section titled “Send a message”curl https://api.mailway.net/v1/send \ -H "Authorization: Bearer $MAILWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": { "email": "billing@yourapp.com", "name": "YourApp" }, "to": "customer@gmail.com", "subject": "Invoice #2042", "html": "<p>Your invoice #2042 is ready.</p>", "text": "Your invoice #2042 is ready." }'const res = await fetch('https://api.mailway.net/v1/send', { method: 'POST', headers: { Authorization: `Bearer ${process.env.MAILWAY_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ from: { email: 'billing@yourapp.com', name: 'YourApp' }, to: 'customer@gmail.com', subject: 'Invoice #2042', html: '<p>Your invoice #2042 is ready.</p>', text: 'Your invoice #2042 is ready.', }),});const mail = await res.json(); // { id: "m.01k8w9…", status: "queued", … }$response = Http::withToken(env('MAILWAY_API_KEY')) ->post('https://api.mailway.net/v1/send', [ 'from' => ['email' => 'billing@yourapp.com', 'name' => 'YourApp'], 'to' => 'customer@gmail.com', 'subject' => 'Invoice #2042', 'html' => '<p>Your invoice #2042 is ready.</p>', 'text' => 'Your invoice #2042 is ready.', ]);
$mailId = $response->json('id'); // "m.01k8w9…"Response — 202 Accepted
Section titled “Response — 202 Accepted”{ "id": "m.01k8w9abcdefghjkmnpqrstvwx", "status": "queued", "scheduled_at": null, "paused": false, "category": null, "project_id": "p.01k8w9…", "routing": { "provider": null, "strategy": null }}id is the mail ID, the permanent identifier that threads through the
console, webhook events, and share links. Webhooks send the same value as
data.mail.uid, and project_id as data.mail.project.uid. status is
queued, scheduled (when scheduled_at is in the future), paused,
captured (a sandbox send — stored, never auto-forwarded), or rejected.
rejected means Mailway received and stored the mail, but a
rule refused it, so it won’t be sent. Its
mail.failed event names the rule.
queued and scheduled are the pending state in
the console and on webhooks. paused and captured are states of their
own, and rejected is the console’s Rejected state.
Request fields
Section titled “Request fields”| Field | Type | Notes |
|---|---|---|
from |
address | Required. "a@b.com" or { "email": …, "name": … } (a display name goes in name; the "Name <a@b.com>" string form isn’t accepted, so use { "email", "name" }). |
to, cc, bcc |
address | address[] | to is required; cc and bcc are optional. At most 50 combined across the three; each entry takes any address form. |
reply_to |
address | address[] | Optional. |
subject |
string | Required. ≤ 989 characters, so the Subject line stays within the email standard’s 998-character limit even when the subject has no space to break at. The whole subject is sent. The console, share links, webhook events, exports, and certificates show its first 255 characters. |
html, text |
string | At least one, ≤ 2 MB each. Send both when you can — some inboxes still want the text part. |
headers |
object | Custom headers (e.g. List-Unsubscribe). A name is printable ASCII with no space or colon, and can’t start with a dot. Each name can appear once, in any case: X-Tag and x-tag in one request are refused. Breaking either rule is a 422 (headers:invalid). These names are reserved and refused (headers:reserved): From, Sender, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, Return-Path, Received, DKIM-Signature, Content-Type, Content-Transfer-Encoding, MIME-Version, and any name that starts with X-Mailway-. A rule’s add_header action replaces a header of the same name, whatever its case. Providers can limit them: MailerSend accepts custom headers over its API only on a Professional plan or higher, and some providers change or drop specific headers (What providers change). |
attachments |
object[] | ≤ 20, each { "filename", "content" (base64), "content_type", "content_id"?, "disposition"? } — 10 MB decoded each, 18.75 MB decoded for all of them together. Base64 makes attachments a third larger, so a 25 MB request body holds at most 18.75 MB of them (Limits). content_id + "disposition": "inline" for inline images, referenced from the HTML as cid:<content_id>. A bare id such as logo is sent as logo@mailway (a Content-ID needs an @), and the HTML’s cid:logo references are pointed at it. A content_id is printable ASCII that makes a valid message ID, such as logo or logo@yourapp.com: no spaces, angle brackets, or doubled dots (attachments.content_id:invalid). content_type is a media type, type/subtype such as application/pdf, and may carry parameters such as ; charset=utf-8. A value without a subtype, a quoted parameter, or a multipart/ type is refused (attachments.content_type:invalid). Without content_type, the attachment is sent as application/octet-stream. Brevo’s and Nuntly’s APIs can’t embed images: through them an inline image arrives as a regular attachment. |
tags |
string[] | Optional. ≤ 10 labels for groups of mails (e.g. password-reset), each ≤ 64 chars of [A-Za-z0-9_-]. They become the project’s tags: you can filter mail by them in the console, a rule can match them (tag_present), and every webhook event lists them in data.mail.tags. Case doesn’t matter within a project: Invoice and invoice are one tag, and webhook events show the spelling used first. Once a project has 1,000 distinct tags, a send with a new one is rejected (tags:limit_reached). Reusing a tag always works, and so does a rule’s tag action. |
metadata |
object | Optional. Your own values for this one mail, such as an order or user ID: ≤ 10 keys, keys ≤ 40 chars, string values ≤ 500 chars. Key order isn’t kept. Every webhook event for the mail carries them in data.mail.metadata, so you can match an event to your records without a lookup. Mailway deletes them with the mail’s content when its retention period ends (webhook deliveries already made keep their copy for 30 days). |
category |
string | One per mail — the reporting bucket your per-category stats group by (e.g. "Password reset"). ≤ 64 chars, letters/digits/space/_-./:, case-sensitive, echoed in the response. A project holds at most 100 distinct categories: reusing one is always free, a 101st new name is rejected (category:limit_reached). Use category for reporting, tags for groups of mails, and metadata to match events to your own records. |
scheduled_at |
RFC 3339 date-time | Defer the send — up to 72 hours ahead (Pro and up; on other plans, 402 scheduling_unavailable). It needs an offset or Z: 2026-08-04T09:00:00Z or 2026-08-04T11:00:00+02:00, and fractions of a second are allowed. A relative value such as +1 hour or tomorrow is refused (scheduled_at:invalid). The response and the stored request carry the UTC time it names (2026-08-04T09:00:00Z), with milliseconds only if you sent a fraction. |
paused |
boolean | Accept + store the message but hold it until released in the console. |
routing.provider |
string | string[] | Pin the send to a provider (or an ordered preference list) attached to the project, by family — amazon-ses, sendgrid, mailgun, mandrill, postmark, brevo, gmail, mailtrap, smtp, resend, mailjet, mailersend, nuntly, smtp2go. Mailway still picks the account’s transport. |
routing.strategy |
string | Override the project’s provider-selection strategy for this send: fallback, round-robin, random, or free-first. |
provider_options |
object | Provider-specific extras, allowlist-validated — keyed by provider family — { "amazon-ses": { "configuration_set": … } } (SES), { "postmark": { "message_stream": … } } (Postmark) — and applied whichever transport the send takes, except Postmark’s stream on a send through Postmark’s API: that doesn’t take effect yet, and the mail goes to Postmark’s default transactional stream. Unknown options are rejected, never silently dropped. |
Every string in the body, at any depth, is trimmed of whitespace (spaces,
tabs, and line breaks) at both ends, html and text included, and an
empty string ("") counts as a field you didn’t send. A blank scheduled_at sends now. A metadata value of "" is
refused (metadata:value_invalid), and so is an empty header value
(headers:invalid). An html of only spaces, with no text, is refused
too (body:required).
There is no template field: send the finished subject and html or
text. A field the table doesn’t list, such as template_id, is refused
with a 422 (body:unknown_key). So the send endpoint has no field for a
template stored at your provider. See
Provider-hosted templates.
tags and attachments are JSON arrays. A JSON object in their place is
refused (tags:invalid, attachments:invalid). An address Mailway can’t
put on a message, such as one with a comment (ada(work)@example.com), is
refused with the field’s own code (from:invalid, to:invalid, and so on).
The full cap sheet — including rate limits and plan quotas — is on one page: Limits & quotas.
Idempotency
Section titled “Idempotency”Pass an Idempotency-Key header (12–40 chars of [A-Za-z0-9_-]) to make
retries safe:
Idempotency-Key: invoice-2042-receiptA repeated key returns the 202 of the mail it first created (the same
id) instead of sending again. Keys are unique per project and never expire: a key is used once, for
the life of the project (see Data retention).
The body is validated before the key is looked up. A retry whose body fails
validation gets that 422, not the original 202, and never a 409.
A retry with the same key gets status and paused as they are when it
arrives, not as they were on the first answer. A mail released since then
reads queued. A mail rejected since then reads rejected, whoever
stopped it: a rule, a person in the console, the suppression list, a
provider’s permanent refusal of the only recipient, or the deletion of its
project. Its webhook event says which:
mail.failed with a reason, or
mail.suppressed for the suppression list. The answer never says what a
provider did: a mail a provider accepted, and a mail whose every attempt
failed (Exhausted), both still read queued, or scheduled if the
request had scheduled_at. Follow delivery through
webhooks or the console.
POST /v1/send/batchSend up to 100 messages in one request — the body is
{ "messages": [ … ] }, each element using the exact /v1/send message
schema. messages is a JSON array: a JSON object in its place refuses the
whole request (messages:invalid). Elements are independent sends:
one failing validation doesn’t sink the rest, which is why the response is
207 Multi-Status — data is an array in your input order, each
element either the normal send object ({ "id": "m.…", "status": … }) or
an error envelope for that message. Check per element; don’t assume
all-or-nothing. Idempotency-Key is not honored on batch, and each
accepted element counts against your quotas.
Send a raw message
Section titled “Send a raw message”POST https://api.mailway.net/v1/send/mime # productionPOST https://api.mailway.dev/v1/send/mime # sandbox: stored, never sent automaticallyWhen your app or its mail library already builds the complete message
(headers and body, RFC 5322), send that message as it is. Mailway relays it
the way its SMTP relay does: byte-for-byte, apart from the
automatic exceptions. The request
is multipart/form-data with two parts:
| Part | Notes |
|---|---|
message |
Required. The message, as a file part. A text field is refused (message:not_a_file). At most 25 MB (413 body:too_large). |
meta |
Required. A JSON object, as a text field or a small JSON file part. As on /v1/send, every string in it is trimmed and "" counts as absent. |
meta field |
Type | Notes |
|---|---|---|
recipients |
string[] | Required. Everyone who gets the mail, Bcc recipients included, as SMTP’s RCPT TO: a JSON array of 1 to 1,000 addresses. A JSON object in its place is recipients:invalid, an empty list is recipients:required, and more than 1,000 addresses is recipients:too_many. An address Mailway can’t put on a message, such as one with a comment, is recipients:invalid too. An address in the message’s To or Cc field that isn’t listed here doesn’t get the mail. An address listed twice gets it once. |
sender |
string | Optional. The envelope sender (SMTP’s MAIL FROM). Without it, Mailway uses the address in the From field. An address Mailway can’t put on a message, such as one with a comment, is refused (sender:invalid). |
category, tags, metadata, paused |
As on /v1/send, with the same limits. |
scheduled_at, routing, and provider_options can’t be set on this
endpoint yet: each is refused with <field>:unsupported, so use /v1/send
for them. Any other key is refused with meta:unknown_key.
curl https://api.mailway.net/v1/send/mime \ -H "Authorization: Bearer $MAILWAY_API_KEY" \ -F 'message=@invoice-2042.eml;type=message/rfc822' \ -F 'meta={"recipients":["customer@gmail.com"],"category":"Invoice"}'The answer is the same 202 as /v1/send, and id is the mail ID.
Idempotency-Key works the same way, and the two endpoints share one rate
limit per key.
Before anything is stored, Mailway refuses (422) a message with no From
field (message:no_from), a NUL byte (message:nul_byte), a bare carriage
return in the header block (message:bare_cr_in_header), or a header line
that starts with a dot (message:header_dot_line). On receipt it adds a
missing Message-ID, made from the mail ID (<m.…@mailway.net>,
@mailway.dev on the sandbox), and a missing Date, and it removes Bcc
and Resent-Bcc fields. Bare line feeds and bare carriage returns are sent
as CRLF.
The project needs at least one provider account that can carry a raw
message: one that sends over SMTP, an Amazon SES or Mailgun account, or an
account an admin enabled re-encoding on
(SMTP mail through API providers).
Otherwise the request is refused with no_raw_mime_provider. Rules see
these mails as their own type (“HTTP API, raw message”), and the actions
that change content skip them, as they skip SMTP mail.
Sandbox
Section titled “Sandbox”Point the same code at https://api.mailway.dev with a mw_test_… key:
messages are validated, stored, and visible in the console with a sandbox
badge — but never forwarded automatically. The payload shape is identical,
so promoting to production is a hostname + key swap — and if a specific
capture turns out to be the real thing, you can
release it from the console
instead of re-running the send.
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
400 |
Mailway couldn’t read the request (request:invalid), or a compressed body doesn’t decode (content_encoding:invalid). |
401 |
Missing or invalid API key, or a key used on the wrong host (mw_live_ on api.mailway.dev, mw_test_ on api.mailway.net). |
402 |
A plan limit — the monthly message quota or data volume, or scheduled_at on a plan without scheduling. The body’s error.code says which. |
413 |
The body is over 25 MB (body:too_large). |
422 |
Validation failed — the body lists field-level errors, e.g. routing_provider_not_configured or an invalid Idempotency-Key. A code never carries a list index: the second to address fails as to:invalid, and error.details[].field says to.1. |
429 |
Rate limited — back off and retry after Retry-After. Every response carries RateLimit and RateLimit-Policy headers, so a client can pace itself before this (rate-limit headers). |
500 |
Mailway failed on its side (server_error). Retry with backoff. On /v1/send and /v1/send/mime, send the same Idempotency-Key. |
Every one of these answers uses the error envelope on
api.mailway.net and api.mailway.dev, whatever the request’s Accept
header.
The full code catalog with handling advice is on the Errors page; when a send doesn’t behave the way you expect, troubleshooting maps the symptom to a fix.
Cookie consent
We may run ads on Google and Reddit. If we do, knowing whether they work needs your OK for one cookie each from them, used only to tie a signup back to the ad that brought it. Analytics here is cookieless either way, and declining changes nothing else.
Change your mind any time with "Cookie choices" in the footer. Details in the privacy policy.