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

Webhooks Pro

Set one HTTPS URL under Settings → Developer. After every forward to one of your aliases we POST an alias.mail_received event there: the alias id, address, label and source, the sender's domain, the delivery id and how many tracking pixels were stripped. It never includes the subject, the body or any address but the alias.

The URL must be https:// on port 443 at a public hostname: no IP addresses, nothing private, local or internal, and not Emcognito itself. We check it when you set it and again before every delivery, and we never follow redirects — a 3xx counts as a refusal, not a retry.

POST https://your.example/hooks/emcognito
Content-Type: application/json
X-Emcognito-Event: alias.mail_received
X-Emcognito-Delivery: 3f1c…
X-Emcognito-Timestamp: 1760745600
X-Emcognito-Signature: sha256=<HMAC-SHA256(secret, raw body)>

{"event":"alias.mail_received","delivery_id":"3f1c…","received_at":1760745600,
 "alias":{"id":"k7m4-9xrt","address":"k7m4-9xrt@emcognito.com","label":"shop","source":"Best Buy"},
 "sender_domain":"shop.example","trackers_blocked":2,"account":{"email_hash":"…"}}

Verify by computing HMAC-SHA256 of the raw request body with the secret shown once when you set the URL, and comparing it to the header. Reply with any 2xx within 10 seconds. Anything else is retried 1, 5 and 25 minutes later, then dropped.

account.email_hash is an opaque, stable identifier for the account the alias belongs to — a keyed hash, so it cannot be derived from or matched against an email address. Use it to tell accounts apart when several point at one endpoint; it does not change when the secret is rotated. (Its value changed once on 18 October 2026 when the keying was added.)

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.