Skip to content

HTTP API

POST https://api.mailway.net/v1/send # production
POST https://api.mailway.dev/v1/send # sandbox — stored, never auto-forwarded

The 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.

Authorization: Bearer mw_live_… # production keys — accepted only on api.mailway.net
Authorization: Bearer mw_test_… # test keys — drive the sandbox

Keys 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.

Terminal window
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."
}'
{
"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.

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.

Pass an Idempotency-Key header (12–40 chars of [A-Za-z0-9_-]) to make retries safe:

Idempotency-Key: invoice-2042-receipt

A 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/batch

Send 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.

POST https://api.mailway.net/v1/send/mime # production
POST https://api.mailway.dev/v1/send/mime # sandbox: stored, never sent automatically

When 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.

Terminal window
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.

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.

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.