Programmatic Alias Creation: What a Developer API for Email Aliases Actually Does

Choosing an email alias service for developers comes down to HTTP contracts, daily caps, and knowing where programmatic access ends. If you need programmatic alias creation from scripts, integration tests, or back-end worker queues, you need predictable JSON endpoints rather than a browser extension wrapped around a consumer inbox.

This guide explains the exact behavior of Emcognito's v1 developer API: the authentication scheme, payload shapes, status codes, burst windows, and daily quotas. We cover what our endpoints deliver, what they deliberately omit, and how to structure code around these boundaries.

The Short Answer: What Emcognito's Developer API Does Today

The v1 surface exposes two endpoints: GET /v1/aliases to list aliases and POST /v1/aliases to generate a new address. The base URL is strictly https://api.emcognito.com/v1 (there is no /api/v1 route prefix).

Authentication requires an HTTP Authorization header using bearer token authentication as defined in RFC 6750: Authorization: Bearer <key>. A valid API key consists of the prefix emk_ followed by 43 URL-safe characters. There is no live or test environment split; a key interacts directly with production data.

When you initiate programmatic alias creation via POST /v1/aliases, the server returns an HTTP 200 OK status code on success, consistent with the representation semantics in RFC 9110, rather than an HTTP 201 Created. The payload nests the record beneath an "alias" key rather than exposing flat root-level fields or an outer status envelope.

The payload schema adheres to specific typing conventions:

• created_at returns as an integer Unix epoch timestamp, not an ISO-8601 string.
• Unset optional string fields return as empty strings ("") rather than null.
• Field names match: id, address, status, created_at, forward_count, label, note, source, category, single_use, and expires_at.

The structural decision payoff is direct: v1 of the Emcognito API creates and lists aliases (GET and POST /v1/aliases). Suspending, resuming and deleting an alias are one-click dashboard actions today; there is no PATCH or DELETE endpoint yet.

Is an Email Alias Service for Developers the Right Layer in Your Stack?

An email alias service for developers handles inbound routing and source identity isolation. It is not an outbound SMTP relay, transactional mail delivery pipeline, or marketing newsletter engine. As outlined in the fundamental transport rules of RFC 5321, email forwarding receives inbound messages and routes them through a transit system to a real underlying destination address without exposing the true inbox address to third parties.

Use programmatic alias creation when generating per-tenant, per-environment, or per-signup forwarding addresses that must persist across operational life cycles. This provides a clean mechanism when evaluating an alternative to consumer-focused platforms that restrict programmatic generation, or when seeking independence from services tightly coupled to desktop operating systems or commercial password managers.

However, evaluate whether our specific infrastructure fits your architectural needs:

• Domain configuration: Emcognito aliases use the shared emcognito.com domain. Custom subdomain support is planned, but custom domains are not available today.
• Codebase and deployment: Emcognito is closed source and runs only as a hosted service; if open source or self-hosting is a requirement, addy.io is the better fit.
• Transport encryption boundaries: Emcognito forwards mail over TLS-encrypted transport and does not read message contents or retain them after delivery, apart from a brief hold on mail that arrives over your monthly forward cap, but it is not end-to-end encrypted. For content confidentiality, pair it with an encrypted mailbox such as Proton Mail or Tuta.
• Data management policies: Emcognito collects no personal information beyond a destination address and does not retain message bodies after delivery, apart from a brief hold on mail that arrives over your monthly forward cap, but it keeps the delivery and operational logs any mail service needs. That is data minimisation, not a no-log policy.
• Service agreements: Emcognito publishes a wind-down commitment: advance notice before a planned shutdown and alias export so accounts can be migrated, on a best-efforts basis. It is not a contractual guarantee.
• Tracking pixel handling: Emcognito strips tracking pixels (the tiny hidden images that report when you open a message) from forwarded mail on every plan, Free included. It does not remove scripts or rewrite links and does not scan for malware.

Your First Programmatic Alias Creation Call

API keys are generated from your Emcognito dashboard when subscribed to a paid plan. Treat this credential as a backend secret and load it from system environment variables. Source: Emcognito source.

To execute a call against our REST API for email aliases, send an authenticated POST request containing JSON metadata:

curl -X POST https://api.emcognito.com/v1/aliases \
  -H "Authorization: Bearer emk_your_key_characters_here_43_chars_total" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "staging-checkout-test",
    "source": "ci-automation-runner",
    "note": "Provisioned for order system acceptance test"
  }'

The API responds with an HTTP 200 status code and a serialized JSON object:

{
  "alias": {
    "id": "ali_9x4K2m8L1pQ",
    "address": "k8j2m4x9p@emcognito.com",
    "status": "active",
    "created_at": 1728907200,
    "forward_count": 0,
    "label": "staging-checkout-test",
    "note": "Provisioned for order system acceptance test",
    "source": "ci-automation-runner",
    "category": "",
    "single_use": false,
    "expires_at": 0
  }
}

When parsing this payload in application code, note these constraints:

1. Nested payload extraction: Target response data inside alias. Do not write parser routines expecting a root-level id or a { status: "success", data: ... } envelope.
2. Identifier persistence: Store the returned id alongside address in your database. Because v1 has no single-resource endpoint (such as GET /v1/aliases/{id}), your internal database serves as the source of truth linking the generated alias to tenant records.
3. Integer timestamp handling: Parse created_at directly as a Unix epoch timestamp in seconds. Ingestion pipelines that expect an ISO-8601 string will fail unless formatted appropriately.
4. Empty string fallback: Optional metadata left unset at generation—such as category—serializes to "" rather than null. Configure object mappers to accept empty strings without throwing type exceptions.

Listing and Paginating Aliases Without Hammering the Burst Limit

Listing records uses the GET /v1/aliases endpoint. Results are paginated sequentially using query cursors: next_cursor and last_key. Iterate across page boundaries by reading the cursor returned in pagination metadata, passing that value to subsequent calls rather than executing arbitrary parallel page requests.

Rate limits operate on two distinct levels: per-minute network burst controls and calendar-day business quotas. POST /v1/aliases returns HTTP 200 with the new alias under "alias". The burst limit is 60 requests a minute per key; its 429 carries a Retry-After header giving the seconds until the window resets. The daily alias-creation cap (50 on Plus, 200 on Pro) resets at 00:00 UTC and its 429 carries no Retry-After. Emcognito sends no X-RateLimit-* headers. Source: Rfc Editor source.

The behavior of rate limiting was confirmed through automated verification: measured live on /v1/aliases 2026-09-20: the 61st call in a minute returned 429 with retry-after: 60. The Retry-After value indicates the whole duration of the rate-limit window. The header communicates the full window duration, ensuring client libraries that honor backoff headers avoid immediate subsequent failures.

Additionally, transient load conditions returning an HTTP 503 Service Unavailable will include a static header of Retry-After: 30. Both the burst 429 and the daily cap 429 return an unadorned JSON error body:

{
  "message": "Rate limit exceeded"
}

To avoid hitting client exceptions, implement this handling pattern:

• Check for the presence of a Retry-After header on any 429 or 503 response.
• If the header is present, pause pipeline execution for the requested duration in whole seconds.
• If an HTTP 429 arrives with no Retry-After header, your key has depleted its daily creation allocation; halt generation attempts until 00:00 UTC.

Daily Caps, Plan Tiers and What Programmatic Alias Creation Costs

On Emcognito, what is metered is forwarded email volume, not alias storage capacity. Accounts on every tier can hold an unlimited number of dormant or active aliases. However, daily alias generation limits are applied to manage network traffic.

Manual alias generation in the web dashboard allows up to 200 creations per day across all tiers, including Free accounts. API-driven generation is reserved for paid subscriptions, with daily volume tiers tied to account level.

• Emcognito Free: Unlimited free email aliases, 100 forwarded messages per month (which can increase to at most 200 through referral credits), with no credit card required. Forwarded messages include a sponsor card at the footer. Inbound delivery logs include Reply securely functionality until November 3, 2026, after which log-based replies require a paid tier. The Free tier does not include API access, outbound composition, or client-based replies.
• Emcognito Plus: $20 per year or $2 per month. Provides 2,500 forwarded messages per month, removes the sponsor card, unlocks composing new mail from any alias, and provides developer API access at 50 alias creations per day.
• Emcognito Pro: $36 per year or $4 per month. Yearly Pro is three months free and is the term customers actually buy. It provides 15,000 forwards per month, compose from any alias at a higher daily send cap, and developer API creation throughput at 200 aliases per day.

Paid accounts introduce direct email composition and bidirectional messaging from common clients (including Gmail, Apple Mail, and Outlook). When sending an outbound message from an existing alias, the delivery process enforces the authentication checks specified in RFC 7489. Outbound messages are accepted only when originating from the account's registered sign-in mailbox with passing SPF validation and an aligned DKIM signature.

Composing also uses a dedicated daily rate limit (20 messages per day on Plus, 100 messages per day on Pro, which ramps up gradually over the first 7 days of an account). Outbound messages consume allowance from your overall monthly message quota alongside inbound forwards. Reaching your daily compose cap will not block inbound forward delivery.

You add a card at checkout and nothing is charged until the trial ends. Signup is passwordless, relying on an emailed magic link rather than passwords or app installations.

Frequently Asked Questions

Can you suspend or delete an alias through the developer API?

v1 of the Emcognito API creates and lists aliases (GET and POST /v1/aliases). Suspending, resuming and deleting an alias are one-click dashboard actions today; there is no PATCH or DELETE endpoint yet. In the web dashboard, clicking Pause alias immediately blocks incoming traffic to that address. Deleting an alias requires confirming the action through an explicit confirmation prompt.

Does Emcognito support custom domains for API-generated aliases?

Emcognito aliases use the shared emcognito.com domain. Custom subdomain support is planned, but custom domains are not available today. Every address minted via the REST API receives a generated local part ending in @emcognito.com.

How are rate limits and daily creation quotas enforced?

POST /v1/aliases returns HTTP 200 with the new alias under "alias". The burst limit is 60 requests a minute per key; its 429 carries a Retry-After header giving the seconds until the window resets. The daily alias-creation cap (50 on Plus, 200 on Pro) resets at 00:00 UTC and its 429 carries no Retry-After. Emcognito sends no X-RateLimit-* headers.

Can client applications reply to forwarded mail directly from mail apps?

On Plus and Pro you can hit Reply in your own mail app (Gmail, Outlook, Apple Mail) on a forwarded message, and Emcognito sends the reply from the alias. It is accepted only from the mailbox you sign in with, and each reply uses one monthly send. On Free, replying from your mail app is a Plus feature; Free accounts can reply from the delivery log with Reply securely until November 3, 2026, after which Reply securely is Plus and Pro only.

Is Emcognito open source or available for self-hosting?

Emcognito is closed source and runs only as a hosted service; if open source or self-hosting is a requirement, addy.io is the better fit. The infrastructure is managed and operated by VectraSEO LLC, reachable at hello@wm.emcognito.com.

Does the developer API provide a sandbox or test environment?

There is no separate sandbox or staging environment. API keys use the literal prefix emk_ followed by 43 URL-safe characters with no live or test distinction. All calls made via the REST API immediately create live forwarding addresses in production storage and draw against your plan's daily creation quota.

If you are automating integration test suites or generating forwarding addresses from your application backend, review the endpoint specifications on the developer alias API documentation.