Building Custom SaaS Integrations: A Guide to the Emcognito Alias API

Wiring an email alias API for custom SaaS integration lets your software provision dedicated, private inbound email addresses directly from backend workflows. Emcognito's v1 API focuses on that core task by exposing two endpoints: GET /v1/aliases to inspect existing records and POST /v1/aliases to generate new ones. The base URL is https://api.emcognito.com/v1; there is no /api/v1 prefix path.

Authentication requires a single HTTP header: Authorization: Bearer <key>. An API key consists of the literal prefix emk_ followed by 43 URL-safe characters. There is no live or test environment split, meaning prefixes like emk_live_, emk_test_, or sk_ do not exist. Requests sent to POST /v1/aliases return HTTP 200 rather than 201 Created. The JSON response nests the record inside an alias object with eleven fields: id, address, status, created_at, forward_count, label, note, source, category, single_use, and expires_at. There is no top-level id or email field, and there is no generic {status, data} envelope.

What the Emcognito Alias API Actually Does in a SaaS Stack

When you evaluate a REST API for email aliases, you need exact schema definitions rather than marketing abstractions. In Emcognito, created_at returns an integer Unix epoch timestamp in seconds, not an ISO-8601 formatted string. If a field such as label or note is left unset during creation, the API returns an empty string ("") rather than null. Deserialization logic in languages like TypeScript, Go, or Rust must parse strings safely without expecting null values.

You must also design around the boundaries of the 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. There is also no single-resource route like /v1/aliases/{id}.

Before writing code, verify how your SaaS requirements map to the capabilities of v1:

• What you can automate: Immediate creation of randomized aliases, metadata attachment (labels, notes, sources, categories), programmatic tagging of single-use aliases, programmatic assignment of expiration timestamps (expires_at), and full directory pagination for database reconciliation.
• What remains manual: Pausing an alias, resuming delivery, and permanent deletion. Pausing is a single click labeled "Pause alias" in the dashboard, and deletion requires a secondary confirmation prompt.
• How routing works: Emcognito creates durable, reply-capable forwarding addresses that route inbound messages to your registered account address without exposing it to the sender. It is an alias architecture, not a temporary or burner inbox.

Choosing a Plan for Programmatic Alias Creation

Before generating API tokens, choose a tier based on your daily creation throughput and outbound messaging needs as outlined on the official Emcognito pricing page. Paid plans are billed annually or monthly, though customers typically purchase annual terms:

• Emcognito Plus: $20 per year (or $2 per month). Includes the developer API capped at 50 created aliases per day, 2,500 forwarded messages per month, ability to compose new mail from any alias, and removal of the promotional sponsor card on forwarded emails.
• Emcognito Pro: $36 per year (or $4 per month). Pro yearly provides three months free compared to the monthly cadence. Includes the developer API capped at 200 created aliases per day, 15,000 forwarded messages per month, and a higher daily outbound send cap for composing messages.
• Emcognito Free: Unlimited total stored aliases, 100 forwarded messages per month, and delivery log replies. The Free plan does not include developer API access or the ability to compose new mail from an alias, but allows up to 200 manual creations per day in the web dashboard without requiring a credit card.

In Emcognito, what is metered is forwarded email volume, not total stored aliases. However, daily creation through the API is restricted: 50 per day on Plus and 200 per day on Pro, resetting at 00:00 UTC. In contrast, manual creation directly within the web dashboard permits 200 aliases per day across all tiers, including Free.

Composing a brand-new message from an alias is a paid feature exclusive to Plus and Pro, available immediately upon starting a 7-day free trial. The Free plan cannot compose new mail from an alias under any circumstance; that is the only functional capability Free lacks. Outbound replies count toward your monthly message quota.

Keep in mind that composing new messages shares the exact same monthly allocation as incoming forwarded mail. On Plus, users have a daily compose limit of 20 messages; on Pro, the limit is 100 messages per day (both ramping up during the first seven days of an account). Because composing draws down your monthly forward pool, high outbound compose activity reduces the remaining bandwidth available for incoming forwards. Both paid tiers offer a 7-day free trial requiring a credit card at checkout, with zero charges billed until the trial finishes.

Creating an Alias Programmatically: A Working POST /v1/aliases Call

To implement automated alias creation, dispatch a JSON POST request to https://api.emcognito.com/v1/aliases. All request body parameters are optional. If you pass an empty JSON object ({}), the API generates a unique nine-character random alias on the shared emcognito.com domain with empty string values for metadata.

cURL Request and Success Payload

curl -X POST https://api.emcognito.com/v1/aliases \
  -H "Authorization: Bearer emk_your_key_here_43_characters_alphanumeric_12" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Tenant Acme Corp",
    "note": "Workspace 9142 billing notifications",
    "source": "saas_billing_service",
    "category": "production_tenants",
    "single_use": false,
    "expires_at": 1793491200
  }'

A successful execution yields an HTTP 200 response (not 201) with the following structure:

{
  "alias": {
    "id": "9f82ab34cd56",
    "address": "k8m2x9q1a@emcognito.com",
    "status": "active",
    "created_at": 1790856000,
    "forward_count": 0,
    "label": "Tenant Acme Corp",
    "note": "Workspace 9142 billing notifications",
    "source": "saas_billing_service",
    "category": "production_tenants",
    "single_use": false,
    "expires_at": 1793491200
  }
}

Node.js Implementation

When handling the response in your backend service, map the returned alias.id and alias.address to your application's user or tenant record in persistent storage.

// aliasService.js
import axios from 'axios';

const EMCOGNITO_API_URL = 'https://api.emcognito.com/v1/aliases';
const API_KEY = process.env.EMCOGNITO_API_KEY; // Must start with emk_
export async function createTenantAlias(tenantId, workspaceName) {
  try {
    const response = await axios.post(
      EMCOGNITO_API_URL,
      {
        label: workspaceName,
        note: Automated alias for tenant ID: ${tenantId},
        source: 'tenant_provisioner',
        category: 'workspaces',
        single_use: false
      },
      {
        headers: {
          'Authorization': Bearer ${API_KEY},
          'Content-Type': 'application/json'
        },
        validateStatus: (status) => status === 200 // Emcognito returns 200 on create
      }
    );
const { alias } = response.data;

// Store mapping in application database
return {
  aliasId: alias.id,
  emailAddress: alias.address,
  createdAtEpoch: alias.created_at
};

  } catch (error) {
    if (error.response && error.response.status === 429) {
      throw new Error(Rate limit encountered: ${error.response.data.message});
    }
    throw error;
  }
}

Integration Pitfalls to Avoid

1. Expecting HTTP 201 Created: The API returns HTTP 200. Strict API clients configured to throw exceptions on any status code other than 201 will abort an otherwise successful call.
2. Parsing created_at as an ISO String: The API returns an integer epoch timestamp (seconds). Invoking standard date parsers directly on the raw value without specifying unit parsing will fail.
3. Unwrapping Missing Root Envelopes: The payload returns {"alias": { ... }}. There is no root-level id, email, or data wrapper. Access properties strictly through the alias key.

Listing and Paginating Aliases with GET /v1/aliases

Reconciling local records against the upstream mail provider prevents state drift. Emcognito exposes GET /v1/aliases for this purpose. Because there are no webhook alerts or update endpoints in v1, querying this collection allows your system to detect if an administrator manually paused an address in the web console.

The endpoint supports cursor pagination via the next_cursor query parameter, which matches the last_key value returned in paginated responses. A Python implementation illustrates the loop:

# reconcile_aliases.py
import os
import requests
import time

API_KEY = os.environ.get("EMCOGNITO_API_KEY")
BASE_URL = "https://api.emcognito.com/v1/aliases"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def fetch_all_aliases():
    all_aliases = []
    cursor = None
while True:
    params = {}
    if cursor:
        params["next_cursor"] = cursor

    resp = requests.get(BASE_URL, headers=HEADERS, params=params)

    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        continue

    resp.raise_for_status()
    data = resp.json()

    aliases = data.get("aliases", [])
    all_aliases.extend(aliases)

    cursor = data.get("last_key")
    if not cursor:
        break

return all_aliases</code></pre>

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. By running a scheduled reconciliation script, your service checks the status property ("active" or "paused") to keep internal databases synchronized with operational changes made via the Emcognito dashboard.
The Two 429s: Burst Limit vs Daily Creation Cap
Proper error handling requires recognizing that Emcognito emits two fundamentally different HTTP 429 Too Many Requests responses depending on which threshold is triggered.



Constraint
Trigger Mechanism
HTTP Status
Retry-After Header
Reset Interval




Per-Key Burst Limit
Exceeding 60 requests in a rolling 60-second window
429 Too Many Requests
Present (integer seconds, typically 60)
End of current 60-second rate limiter window



Infrastructure Protection
Temporary rate-limiter backpressure
503 Service Unavailable
Present (fixed at 30 seconds)
30 seconds



Both 429 responses return an identical, unformatted JSON payload: {"message": "Rate limit exceeded"} or {"message": "Daily alias creation limit reached"}. Because no standard rate-limit headers (such as limits or remaining request counts) are present, your API client must use the presence of the Retry-After header to determine its backoff strategy:

If the 429 includes a Retry-After header, pause execution for the designated number of seconds and retry the request. (As documented on the developer alias API reference, live measurements taken on September 20, 2026, confirmed that the 61st call within a 60-second window receives a 429 with retry-after: 60).
If the 429 arrives without a Retry-After header, your account has consumed its daily allocation. Cease retrying immediately and queue all pending creation jobs until 00:00 UTC.

Design Patterns for Automated Alias Creation in Your Product
When incorporating an alias API into customer-facing applications, several architectural patterns provide reliable isolation and security.
1. Per-Tenant Address Isolation
Assigning a distinct inbound alias to each workspace or organization unit simplifies message segregation. By populating the source parameter with the microservice identifier and category with the customer's organization ID, your customer support staff can trace delivery routes in the dashboard without parsing raw server logs.
2. Ephemeral Inbound Channels
For automated workflows like single-sign-on verifications, trial signups, or transient webhook ingestion, set single_use: true or pass an integer timestamp to expires_at. When the timestamp elapses, inbound forwarding stops immediately, ensuring dormant integration endpoints do not accumulate ongoing traffic.
3. Quota Deflection and Queue Management
Because automated alias creation draws against a hard daily ceiling (50 per day on Plus, 200 per day on Pro), provisioning jobs must not execute directly within user-facing synchronous request cycles. Run creation requests through a durable worker queue (such as Celery, BullMQ, or SQS). If the queue consumer detects a daily cap 429, it can suspend processing until the 00:00 UTC reset without dropping customer requests.
4. Manual Offboarding Runbooks
Because deleting or pausing an alias cannot be executed through the API, customer offboarding procedures must account for dashboard interventions. If a tenant terminates their SaaS subscription, flag the record in your database as inactive so incoming webhooks ignore subsequent mail. Later, an administrator can pause or delete the corresponding address in the web console.
What the Alias API Does Not Cover, and How to Plan Around It
To avoid development dead-ends, verify your technical architecture against the architectural constraints of the Emcognito platform before committing resources.
Emcognito aliases currently use the shared emcognito.com domain. Custom subdomain support is planned, but custom domains are not available today. If your product requires inbound mail routed through an organization-owned custom host, Emcognito is not the right tool for that specific requirement. Similarly, 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.
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. Emcognito is not a zero-knowledge service. It does not read or analyse message contents, or retain them after delivery, apart from a brief hold on mail that arrives over your monthly forward cap, but it necessarily handles mail in readable form in order to deliver it.
Regulatory frameworks such as the FTC Data Security Guidance highlight the importance of minimizing stored consumer data. 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.
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. Review our side-by-side platform breakdowns on the Emcognito comparison page to evaluate features against other forwarding tools.



System Requirement
Supported in Emcognito?
Architecture Workaround / Target Vendor




Custom domain support
No
Emcognito aliases currently use the shared emcognito.com domain. Custom subdomain support is planned, but custom domains are not available today.


Self-hosted deployment
No (hosted SaaS only)
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.


Automated alias deletion
No API endpoint
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.


End-to-end encryption
No
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.


Programmatic email forwarding
Yes
Standard forwarding to your destination inbox.



For organizations operating customer-facing email ingestion pipelines, staying vigilant against incoming threats is an operational requirement. As outlined in the FTC phishing guidance, unexpected communications should be treated with caution, especially when processing automated notifications. In addition, the FTC guidance on how websites and apps collect and use information reinforces why engineering teams use compartmentalized addresses to isolate tracking and trace downstream data exposure.
Frequently Asked Questions
What does an Emcognito API key look like, and is there a separate test key?
An Emcognito API key consists of the literal string prefix emk_ followed by 43 URL-safe alphanumeric characters. There is no separate test key or sandbox environment; all requests execute directly against live account resources.
Does POST /v1/aliases return 201 Created?
No, the endpoint returns an HTTP 200 OK status on success. The payload nests the minted record inside an alias object containing the address, epoch timestamp, and configured metadata.
Why did my alias creation call return 429 with no Retry-After header?
A 429 status code lacking a Retry-After header indicates that your account has reached its daily creation cap (50 per day on Plus, 200 per day on Pro). This application-level limit clears at 00:00 UTC. In contrast, the per-key burst limit (60 requests per minute) does return a Retry-After header.
Can I suspend or delete an alias through the 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. State modifications must be performed by logging into the web dashboard.
How many aliases can I create per day on Plus versus Pro?
 Both tiers reset daily usage at 00:00 UTC. If creating aliases manually via the web dashboard, all tiers (including Free) permit up to 200 creations per day.
Next Step
To begin your implementation, review the full endpoint schemas in the developer alias API reference, confirm the two v1 endpoints and the emk_ key format against your architecture plan, and start a 7-day trial on Plus or Pro when you are ready to create aliases from your own code.