Email Alias API — Create aliases programmatically.

Quick start

Create an alias:

curl -X POST https://api.emcognito.com/v1/aliases \
  -H "Authorization: Bearer emk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"label": "acme-signup"}'

List your aliases:

curl https://api.emcognito.com/v1/aliases \
  -H "Authorization: Bearer emk_your_key"

The POST body is optional JSON. label, note, source and category are free text; single_use (boolean) burns the alias after one forwarded message, and expires_at (epoch seconds, between 5 minutes and 366 days out) schedules its deletion.

Endpoints

Responses

GET /v1/aliases returns a page of aliases plus an opaque cursor. Pass next_cursor straight back as ?last_key= to fetch the next page; it is null on the last one.

{
  "aliases": [
    {
      "id": "01hq…",
      "address": "01hq…@emcognito.com",
      "status": "active",
      "created_at": 1786000000,
      "forward_count": 3,
      "note": "",
      "source": "",
      "label": "acme-signup",
      "category": "",
      "single_use": false,
      "expires_at": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

POST /v1/aliases returns the one alias it created, in the same shape, under alias:

{ "alias": { "id": "01hq…", "address": "01hq…@emcognito.com", … } }

Two fields appear only when they apply: replies_enabled when replies have been configured on the alias, and suspended_reason when status is suspended.

Rate limits

Two separate budgets apply. The per-minute burst limit is counted per API key and covers every call; the daily cap counts alias creation only, so listing your aliases never consumes it.

Both return 429. The burst limit clears within the minute; the daily cap resets at 00:00 UTC.

Authentication

Every request carries your API key as a Bearer token in the Authorization header. Keys are managed at /settings/developer — one key per account. Rotating or revoking a key invalidates the old one immediately, and keys only work while the account is on a Plus or Pro plan.

Errors

Plan and key errors carry {"code", "description"}; the rest carry {"message"}. Key off the status and the code where present.