Email Alias API — Create aliases programmatically.
The Emcognito API is a small REST surface for creating and listing email aliases from your own code — scripts, CI pipelines, signup flows, or internal tools. Authenticate with a single API key sent as a Bearer token, send and receive JSON, and every alias you create behaves exactly like one made in the dashboard. API access is included with Plus and Pro plans.
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 all accepted — and the response is the created alias item.
Endpoints
| Method | Path | Purpose | Limits |
|---|---|---|---|
POST | /v1/aliases | Create an alias. Optional JSON body: label, note, source, category. | Plus 50/day · Pro 200/day |
GET | /v1/aliases | List your aliases. Cursor pagination via last_key. | — |
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
| Status | Meaning |
|---|---|
401 | Invalid or revoked API key. |
403 | plan_required — the account is on the Free plan; the API needs Plus or Pro. |
429 | Over the daily creation cap. Retry after the daily window resets. |
Frequently asked questions
Is there a free API tier?
No. API keys are available on Plus ($2/month) and Pro ($4/month). Alias creation in the dashboard and extension is free and unlimited — the API is for programmatic use, and keeping it on paid tiers is how we keep it abuse-resistant and stable.
How many API keys can I have?
One per account. Generating a new key rotates the old one, which stops working immediately — the same applies when you revoke a key.
What happens when I hit the daily cap?
POST /v1/aliases returns 429 until the daily window resets. Your existing aliases and mail forwarding are unaffected.
Can I delete or suspend aliases through the API?
Not yet. v1 covers creating and listing aliases; suspend, resume, and delete from the dashboard.