Mailware API · v1

A throwaway inbox in three calls.

No sign-up, no API key, no SDK. Make an inbox, use the address anywhere, then ask for the code. The last call waits for the email, so you never write a polling loop.

1
Make an inbox POST /v1/inbox You get an address and a token.
2
Use the address emma.carter91@mailware.app Sign up anywhere with it.
3
Get the code GET /v1/inbox/{token}/code Waits until the email lands.

Try it live

This is the real API.

Press “Make an inbox” to start.

// the response shows up here

Copy & paste

The whole thing, in your language.

# 1. Make an inbox
curl -X POST https://mailware.app/v1/inbox
# → {"address": "emma.carter91@mailware.app", "token": "x7Hq2LxR…", …}

# 2. Sign up somewhere with that address.

# 3. Get the code. This waits up to 60 seconds for the email.
curl "https://mailware.app/v1/inbox/x7Hq2LxR…/code?timeout=60"
# → {"code": "482913", …}

const api = "https://mailware.app/v1";

// 1. Make an inbox
const inbox = await fetch(`${api}/inbox`, { method: "POST" }).then(r => r.json());
console.log(inbox.address); // sign up with this

// 3. Get the code (waits up to 60 seconds)
const { code } = await fetch(`${api}/inbox/${inbox.token}/code?timeout=60`).then(r => r.json());
console.log(code); // "482913"

import requests

api = "https://mailware.app/v1"

# 1. Make an inbox
inbox = requests.post(f"{api}/inbox").json()
print(inbox["address"])  # sign up with this

# 3. Get the code (waits up to 60 seconds)
code = requests.get(f"{api}/inbox/{inbox['token']}/code", params={"timeout": 60}).json()["code"]
print(code)  # "482913"

import { test, expect } from "@playwright/test";

const api = "https://mailware.app/v1";

test("sign up with a real inbox", async ({ page }) => {
  const inbox = await (await fetch(`${api}/inbox`, { method: "POST" })).json();

  await page.goto("https://your-app.example/signup");
  await page.fill("input[type=email]", inbox.address);
  await page.click("text=Create account");

  const { code } = await (await fetch(`${api}/inbox/${inbox.token}/code?timeout=60`)).json();
  expect(code).not.toBeNull();
  await page.fill("input[name=code]", code);
});

Every endpoint

Ten URLs. You'll use three.

All URLs start with https://mailware.app/v1. Every answer is JSON. The {token} in the URL is the only key: no headers, no API keys.

POST/inboxMake an inbox

Everything is optional. Send options as query parameters or a JSON body.

`name`	The part before the `@`. Random if you leave it out. 3–40 letters, numbers, `.` `-` `_`
`domain`	One of `/domains`. Defaults to the first one.
`minutes`	How long it lives: `60` (default), `10`, `1440` or `10080`.

{
  "address": "emma.carter91@mailware.app",
  "token": "x7Hq2LxRqK9…",
  "url": "https://mailware.app/v1/inbox/x7Hq2LxRqK9…",
  "expires_at": "2026-10-22T14:36:09.000Z",
  "expires_in": 600,
  "messages": []
}

GET/inbox/{token}/codeGet the next code

Returns the one-time code from the next email that has one. If none has arrived yet, it waits up to timeout seconds (default 30, max 60). Each code is handed out once, so call it again for the next signup.

{ "code": "482913", "message_id": "kq93Zt…", "from": "no-reply@nimbus.app", "subject": "Your Nimbus verification code" }

// nothing arrived in time:
{ "code": null }

GET/inbox/{token}/linkGet the next verify link

Same as /code, for “confirm your email”, password-reset and magic sign-in links.

{ "link": "https://parcelly.com/confirm/a81f3c", "kind": "Verify link", "message_id": "…", "from": "hello@parcelly.com", "subject": "Confirm your email" }

GET/inbox/{token}/nextGet the next email

The next unread email in full, waiting like /code does. Returns { "message": null } on timeout.

{
  "message": {
    "id": "kq93Zt…",
    "from": "no-reply@nimbus.app",
    "from_name": "Nimbus",
    "subject": "Your Nimbus verification code",
    "preview": "Use 482 913 to verify your email.",
    "code": "482913",
    "link": null,
    "received_at": "2026-10-22T14:27:31.000Z",
    "to": "emma.carter91@mailware.app",
    "text": "Verify your email\n\nUse 482 913 to verify…",
    "html": "<h1>Verify your email</h1>…",
    "attachments": []
  }
}

GET/inbox/{token}See the whole inbox

The same shape as when you made it, with messages filled in, newest first. Doesn't wait.

GET/inbox/{token}/messages/{id}Read one email

The full email: text, sanitized html, and attachments with a download url each.

POST/inbox/{token}/testSend yourself a test email

Drops a real test email (with a 6-digit code) into the inbox. Handy for checking your integration.

POST/inbox/{token}/extendKeep it longer

Adds 5 minutes. Returns the inbox.

DELETE/inbox/{token}Burn it now

Deletes the inbox and every email in it. Returns { "ok": true }. DELETE /inbox/{token}/messages/{id} deletes one email.

GET/domainsList domains

{ "domains": ["mailware.app", "mailware.email"] }

Good to know

The rules, briefly.

The token is a password. Anyone with it can read the inbox. Don't put it in public logs or URLs you share.
Inboxes burn. After expires_in seconds the inbox and its mail are gone for good. Nothing is kept or logged.
Waiting is free. /code, /link and /next hold the request open until mail arrives (max 60 s). If you get null, just call again.
Works from browsers. CORS is open, so fetch from any page works.
Limits. 20 new inboxes per minute per IP, 12 open waiting requests per IP, 30 emails per minute into one inbox, and 10 MB per email. Over a limit you get 429 with a Retry-After header.
Receive only. Mailware never sends mail out.

Errors

When something's off.

Errors use normal HTTP status codes and always look like this:

{ "error": "not_found", "message": "This inbox has burned, or the token is wrong." }

`400`	`bad_request`, `invalid`, `reserved`, `domain`	Something in what you sent isn't allowed. The message says what.
`404`	`not_found`	The inbox burned or the token is wrong. Make a new one.
`409`	`taken`	That `name` is in use. Pick another or leave it out.
`429`	`rate_limited`	Slow down. Wait `Retry-After` seconds.
`503`	`full`	Mailware is at capacity. Try again shortly.