Documentation

EmailAlias Docs

Everything you need to integrate with EmailAlias — from getting started to full API reference.

Getting Started

Quick Start Guide
Creating Your First Alias
Setting Up Custom Domains
Understanding Encryption

API Reference

Authentication
Aliases
Custom Domains
Billing & Subscription
Exposure Intelligence

Quick Start

Create an account

Get your API key

After logging in, navigate to Settings → API Keys to generate your access token.

Make your first API call

Use the API to create your first alias programmatically.

curl -X POST https://api.emailalias.io/api/aliases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "shopping"}'

Authentication

All API requests require a Bearer token in the Authorization header. You can use either an API key (recommended) or a JWT token.

API Key (Recommended)

Generate from Settings → API Keys. Premium plan required. Keys don't expire.

Authorization: Bearer ea_live_...

JWT Token

Obtained via the magic-link login flow. Expires after 24 hours.

Authorization: Bearer eyJ...

Security: API keys are hashed before storage — we never store the raw key. Keep your key secret. If compromised, delete it from Settings and create a new one.

Guides

Creating Your First Alias

1. Log in to your dashboard and click Create Alias.
2. Choose a type: Random (auto-generated), Custom (your own name), Service (per-app), or Tagged.
3. Select a domain — system domains (email91.com) or your verified custom domain.
4. Add an optional label (e.g., "Shopping", "Newsletter") for easy identification.
5. Click Create — your alias is immediately active and ready to receive emails.

# Via API
curl -X POST https://api.emailalias.io/api/aliases \
  -H "Authorization: Bearer ea_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias_type": "random", "label": "Shopping", "domain": "email91.com"}'

DNS Configuration for Custom Domains

Every custom domain requires 4 DNS records for full email authentication:

Record	Type	Value
MX	MX	10 inbound-smtp.us-east-1.amazonaws.com
SPF	TXT	v=spf1 include:amazonses.com ~all
DMARC	TXT	v=DMARC1; p=quarantine; rua=mailto:dmarc@emailalias.io
DKIM	CNAME	Auto-generated via SES

Domain is verified only when ALL checks pass (MX + SPF + DKIM + DMARC + ownership TXT).

Replying from Aliases

Premium users can send emails from any alias. The recipient only sees the alias address.

curl -X POST https://api.emailalias.io/api/send-email \
  -H "Authorization: Bearer ea_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_id": "uuid-of-your-alias",
    "to_email": "recipient@example.com",
    "subject": "Hello",
    "body": "Sent from my alias!"
  }'

Breach Alert Response Guide

When an alias appears in a data breach:

1. You'll receive an exposure alert in your dashboard and via email.
2. Identify which alias was compromised — each service has its own alias.
3. Disable the compromised alias to stop receiving spam/phishing.
4. Create a new alias for that service and update your account there.
5. Your real email remains safe — only the alias was exposed.

# Check exposure via API
curl https://api.emailalias.io/api/analytics/exposure \
  -H "Authorization: Bearer ea_live_YOUR_KEY"

# Disable compromised alias
curl -X PATCH https://api.emailalias.io/api/aliases/ALIAS_ID \
  -H "Authorization: Bearer ea_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

API Key Management

Premium users can create up to 5 API keys for programmatic access.

• Go to Settings → API Keys and click Create.
• Name your key (e.g., "Production", "CI/CD").
• Copy the key immediately — it's only shown once.
• Use the key as a Bearer token in the Authorization header.
• Delete and rotate keys anytime from Settings.

API keys are prefixed with ea_live_ and never expire. Delete a key to revoke access.

Rate Limits

Plan	Rate Limit	Burst
Free	60 requests/minute	10 requests/second
Premium	300 requests/minute	30 requests/second

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Authentication

Passwordless magic-link authentication. No passwords to remember or leak.

POST/api/auth/magic-link

Send a magic link to the user's email for passwordless login.

Request Body

{ "email": "user@example.com" }

Response

{ "message": "Magic link sent to your email" }

POST/api/auth/verify

Verify a magic link token and receive an access token.

Request Body

{ "token": "abc123..." }

Response

{ "access_token": "eyJ...", "token_type": "bearer", "user": { ... } }

GET/api/auth/meAuth Required

Get the currently authenticated user's profile.

Response

{ "id": "uuid", "email": "...", "plan": "free|premium", "alias_count": 3 }

Aliases

Create, manage, and monitor your encrypted email aliases.

GET/api/aliasesAuth Required

List all aliases for the authenticated user.

Response

{ "aliases": [{ "id": "uuid", "address": "abc@emailalias.io", "label": "shopping", "enabled": true, "emails_forwarded": 42, "created_at": "..." }] }

POST/api/aliasesAuth Required

Create a new encrypted email alias.

Request Body

{ "label": "shopping", "domain_id": null }

Response

{ "id": "uuid", "address": "x7k9m@emailalias.io", "label": "shopping", "enabled": true }

PATCH/api/aliases/{alias_id}Auth Required

Update an alias (toggle enabled/disabled, change label).

Request Body

{ "enabled": false, "label": "old-shopping" }

Response

{ "id": "uuid", "address": "...", "enabled": false, "label": "old-shopping" }

DELETE/api/aliases/{alias_id}Auth Required

Permanently delete an alias. This action cannot be undone.

Response

{ "message": "Alias deleted" }

GET/api/aliases/{alias_id}/statsAuth Required

Get forwarding statistics and breach status for a specific alias.

Response

{ "emails_forwarded": 42, "emails_blocked": 5, "last_forwarded_at": "...", "breach_detected": false }

Custom Domains

Add and verify custom domains for branded aliases. Premium plan required.

GET/api/domainsAuth Required

List all custom domains for the authenticated user.

Response

{ "domains": [{ "id": "uuid", "domain": "example.com", "verified": true, "dns_records": [...] }] }

POST/api/domainsAuth Required

Add a new custom domain. Returns DNS records to configure.

Request Body

{ "domain": "example.com" }

Response

{ "id": "uuid", "domain": "example.com", "verified": false, "dns_records": [{ "type": "MX", "name": "@", "value": "mx.emailalias.io", "priority": 10 }, { "type": "TXT", "name": "@", "value": "v=spf1 include:emailalias.io ~all" }] }

POST/api/domains/{domain_id}/verifyAuth Required

Trigger DNS verification for a custom domain.

Response

{ "verified": true, "domain": "example.com" }

DELETE/api/domains/{domain_id}Auth Required

Remove a custom domain and all associated aliases.

Response

{ "message": "Domain removed" }

Billing & Subscription

Manage subscriptions and billing via Stripe integration.

POST/api/billing/create-checkoutAuth Required

Create a Stripe checkout session for Premium subscription.

Request Body

{ "price_id": "price_monthly|price_yearly", "success_url": "...", "cancel_url": "..." }

Response

{ "checkout_url": "https://checkout.stripe.com/..." }

POST/api/billing/portalAuth Required

Create a Stripe billing portal session for subscription management.

Response

{ "portal_url": "https://billing.stripe.com/..." }

GET/api/billing/subscriptionAuth Required

Get the current user's subscription status.

Response

{ "plan": "premium", "status": "active", "current_period_end": "...", "cancel_at_period_end": false }

POST/api/billing/webhook

Stripe webhook endpoint for subscription lifecycle events (server-to-server).

Response

{ "received": true }

Exposure Intelligence

Monitor aliases for data breaches and exposure events.

GET/api/exposure/breachesAuth Required

List all detected breaches affecting your aliases.

Response

{ "breaches": [{ "alias_id": "uuid", "alias_address": "...", "breach_name": "ExampleCorp", "breach_date": "2025-01-15", "exposed_data": ["email", "password_hash"], "detected_at": "..." }] }

GET/api/exposure/scoreAuth Required

Get your overall exposure risk score based on alias activity.

Response

{ "score": 15, "risk_level": "low", "total_aliases": 12, "exposed_aliases": 1, "recommendations": [...] }

Error Codes

Code	Status	Description
400	Bad Request	Invalid request body or missing required fields.
401	Unauthorized	Missing or invalid authentication token.
403	Forbidden	Insufficient permissions (e.g., free plan accessing premium features).
404	Not Found	The requested resource does not exist.
409	Conflict	Resource already exists (e.g., duplicate domain).
422	Unprocessable Entity	Validation error in request body.
429	Too Many Requests	Rate limit exceeded. Retry after the interval in X-RateLimit-Reset.
500	Internal Server Error	An unexpected error occurred. Contact support if this persists.

// Error response format
{
  "detail": "Human-readable error message",
  "code": "ERROR_CODE",
  "status": 400
}

SDKs & Libraries

Official client libraries coming soon. In the meantime, use any HTTP client with our REST API:

Python

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
r = requests.post(
    "https://api.emailalias.io/api/aliases",
    json={"label": "shopping"},
    headers=headers,
)
print(r.json())

JavaScript

const res = await fetch(
  "https://api.emailalias.io/api/aliases",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ label: "shopping" }),
  }
);
const data = await res.json();

Ready to integrate?

Create a free account and start building with the EmailAlias API.

Get API Key — Free Talk to Engineering