REST API

Programmatically create and manage aliases with a bearer token.

Everything you can do on the site, you can do from a script. Grab a token from /manage-email, attach it as a bearer header, and you're in.

Authentication

All requests require an Authorization header:

Authorization: Bearer ef_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens are tied to the email that generated them. Aliases created via the API automatically forward to that email, already verified.

Managing tokens. Sign in at /manage-email, scroll to API tokens. You'll see a Create token button — label it (e.g. browser extension, home-server script) and copy the token. We only show it once. Lost tokens can't be recovered — revoke and create a new one.

Base URL

https://emailforward.xyz/api/v1

Rate limits

Writes (POST / PATCH / DELETE): 60 per hour per token.
Reads (GET): 300 per hour per token.

Exceeding a limit returns 429 with a Retry-After header.

Endpoints

`POST /aliases`

Create a new alias. The caller's email is added as a verified recipient automatically.

Body (all fields optional):

{ "prefix": "shopping-amz" }

Omit prefix for a random 6-char local part. prefix must be 3–30 chars, lowercase letters/digits/._-, start and end alphanumeric. On @emailforward.xyz, role names (hello, admin, postmaster, privacy, …) are reserved. On a custom domain only reply is reserved (two-way reply tokens).

Response 201:

{
  "shortId": "aB3dE7fG",
  "alias": "shopping-amz@emailforward.xyz",
  "createdAt": "2026-04-22T10:00:00.000Z",
  "forwardsTo": "you@example.com"
}

Errors: 400 invalid prefix · 409 alias taken · 429 rate-limited.

`GET /aliases`

List aliases forwarding to the caller's email.

Response 200:

{
  "aliases": [
    {
      "shortId": "aB3dE7fG",
      "alias": "shopping-amz@emailforward.xyz",
      "createdAt": "2026-04-22T10:00:00.000Z",
      "isActive": true,
      "isPaused": false
    }
  ]
}

`GET /aliases/:shortId`

Fetch alias detail and recipient list.

Response 200:

{
  "shortId": "aB3dE7fG",
  "alias": "shopping-amz@emailforward.xyz",
  "createdAt": "2026-04-22T10:00:00.000Z",
  "isActive": true,
  "isPaused": false,
  "forwards": [
    { "id": 1, "type": "email", "email": "you@example.com", "verified": true, "createdAt": "…" }
  ]
}

`PATCH /aliases/:shortId`

Pause or resume the alias.

Body:

{ "isPaused": true }

`DELETE /aliases/:shortId`

Unlink the caller's email from the alias. If no recipients remain, the alias is deleted entirely.

Response 200:

{ "deleted": true, "aliasDeleted": false }

`GET /aliases/:shortId/history`

Last emails received by the alias. Defaults to 50, max 200.

Query: ?limit=100

Response 200:

{
  "history": [
    {
      "id": "clx…",
      "from": "news@example.com",
      "subject": "Your weekly roundup",
      "status": "done",
      "receivedAt": "2026-04-22T09:55:00.000Z",
      "forwardedAt": "2026-04-22T09:55:02.000Z",
      "telegramSentAt": null,
      "lastError": null,
      "recipientTag": null
    }
  ]
}

Examples

Create an alias with curl:

curl -X POST https://emailforward.xyz/api/v1/aliases \
  -H "Authorization: Bearer $EF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"shopping-amz"}'

List aliases:

curl https://emailforward.xyz/api/v1/aliases \
  -H "Authorization: Bearer $EF_TOKEN"

Pause an alias:

curl -X PATCH https://emailforward.xyz/api/v1/aliases/aB3dE7fG \
  -H "Authorization: Bearer $EF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isPaused":true}'

Versioning

The /v1 prefix is stable. Breaking changes land under /v2; bug fixes and additions happen in-place.