API for developers

QuickInbox's temporary email generator is available as a simple JSON API, free to use. There's no signup and no API key — just call the endpoints below. This is the same API the website itself uses.

Base URL: https://quickinbox.net

POST /api/generate

Creates a new temporary address that lives for a chosen number of minutes.

Request body (JSON)

{
  "minutes": 10,
  "customName": "johnsmith"
}

minutes must be a whole number from 5 to 30. customName is optional — omit it (or leave it out entirely) to get a random address like on the website. If provided, it becomes the part before the @ and must be 3-30 characters: lowercase letters, digits, dots, hyphens, or underscores, and can't start or end with one of those symbols. Returns 409 Conflict if that name is already taken or reserved.

Example response

{
  "address": "johnsmith@quickinbox.net",
  "expiresAt": 1893456000,
  "minutes": 10
}

expiresAt is a Unix timestamp (seconds) for when the address and its messages are permanently deleted.

GET /api/inbox/:local

Fetches the current messages for an address. :local is just the part before the @ — for a1b2c3d4e5@quickinbox.net, that's a1b2c3d4e5.

Example response

{
  "address": "a1b2c3d4e5@quickinbox.net",
  "expiresAt": 1893456000,
  "messages": [
    {
      "id": "b2c3d4e5-...",
      "from": "sender@example.com",
      "subject": "Confirm your signup",
      "text": "...",
      "html": "...",
      "receivedAt": 1893455460
    }
  ]
}

Returns a 404 with an error field if the address has expired or never existed. Polling every few seconds while the address is active is fine.

Limits

To keep the service usable for everyone, address creation (POST /api/generate) is rate-limited to about 10 requests per minute per IP address. There's currently no limit specific to GET /api/inbox/:local beyond normal fair use — please don't hammer it faster than once every second or two per address.

This API is provided as-is and free of charge. Addresses and messages are deleted automatically once they expire, exactly like on the website — there's no way to recover them afterward.

Permanent (account-based) addresses

Everything above is a temporary address (5-30 minutes). A visitor can also create a free account to claim a permanent address that never expires. These endpoints use a session cookie (set on signup/login) instead of an API key — they're meant for the website itself, but work from any client that keeps cookies across requests.

One account can hold up to 10 permanent addresses, each identified by its local part (the text before @quickinbox.net).

POST /api/account/signup

Body: { "username": "johnsmith", "password": "at least 8 chars", "localPart": "johnsmith" }. Creates the account, claims localPart as its first permanent address, and sets the session cookie. Returns 409 if the username or address name is taken.

POST /api/account/login

Body: { "username": "...", "password": "..." }. Sets the session cookie on success.

POST /api/account/logout

Clears the session cookie.

GET /api/account/me

Returns { "username", "addresses": [{ "local", "address", "forwardTo", "createdAt" }, ...], "maxAddresses" } for the signed-in account, or 401 if not signed in.

POST /api/account/address/add

Body: { "localPart": "another-name" }. Claims an additional permanent address on the signed-in account. Returns 409 if the name is taken or the account is already at its 10-address limit.

POST /api/account/address/remove

Body: { "local": "another-name" }. Permanently deletes one address (and its messages) from the signed-in account, without affecting its other addresses. Returns 404 if that address isn't owned by the signed-in account.

GET /api/account/messages

Query string: ?local=another-name. Returns { "address", "messages": [...] } for that address's permanent inbox (same message shape as /api/inbox/:local). Requires the session cookie and that the address belong to the signed-in account — unlike temporary addresses, a permanent inbox can't be read just by knowing its address.

POST /api/account/forward

Body: { "local": "another-name", "email": "you@example.com" } (empty string for email disables it). Sets or clears forwarding for one address on the signed-in account.

POST /api/account/delete

No body required. Deletes the entire account: every permanent address it holds, all of their messages, and the login itself. Clears the session cookie.