Email Alias API: Create and Manage Aliases in Code

If you’d rather generate addresses in code than click a button, the email alias API turns everything the dashboard does into calls your programs can make. It’s a straightforward REST API: authenticate with a key, then create, list, update, and delete aliases — plus manage domains, destinations, and filters — exactly as you would by hand, but automated. This guide covers what the email alias API can do, how to authenticate, a working example, and the extras that make it developer-friendly: an OpenAPI spec and a ready-made MCP server for AI tools.

What the Email Alias API Is

The email alias API is a REST API — the same kind of interface you’d use to integrate any modern web service — that exposes your EmailAlias account to code. Anything you can do in the dashboard, from generating a fresh alias to changing where it forwards, you can also do with an HTTP request. It speaks JSON, uses ordinary HTTP methods, and lives at a single base address: https://emailalias.io/api.

That means aliasing can become part of your own software rather than a manual chore. A signup script can mint a new alias for each account it registers; a backend can create a fresh forwarding address per customer; an internal tool can list and tidy your aliases on a schedule. The API is the bridge between EmailAlias’s privacy features and whatever you’re building — and it’s the same engine the dashboard itself runs on, so nothing is second-class about it. For the full developer picture, our developer overview pulls the pieces together.

What You Can Do With It

With a key, your code can reach the same endpoints the dashboard uses. The core ones:

• Create an alias. Generate a random alias, or specify a custom one, in a single request — the workhorse call for automating signups.
• List your aliases. Pull the full set to audit, sync, or display them in your own tool.
• Update an alias. Change where it forwards, toggle it on or off, or adjust its settings.
• Delete an alias. Remove one you no longer need.
• Manage the rest of your account. The domains, destinations, analytics, and sender-filter endpoints are all reachable too, so a script can do more than just mint addresses.

In other words, the API isn’t a cut-down subset — it’s programmatic access to your account. Whether you want to create thousands of aliases over time or just automate the one repetitive task you do by hand today, the building blocks are the same calls the dashboard makes on your behalf every day. It extends the everyday flow of creating and managing aliases into anything you can script.

How the Email Alias API Works

Authentication is a personal API key. In Settings you generate a key that starts with ea_live_, and you send it on every request as a standard HTTP Bearer token in the Authorization header. The server checks the key, identifies your account, and runs the request as you — the same permissions you have in the dashboard.

A few details worth knowing:

• The key is shown once. When you create a key, the full value is displayed a single time. Copy it then and store it safely (in a secrets manager or environment variable); afterwards only a short prefix is shown, and the full key is stored hashed, so it can’t be recovered — you’d generate a new one instead.
• It’s a Bearer token. Every call carries Authorization: Bearer ea_live_... — the same pattern used across modern APIs, so any HTTP client works.
• Responses are JSON. Create an alias and you get the new address back in the response body, ready to use immediately.

Because it’s a plain REST API with Bearer auth, you don’t need any special library — cURL, your language’s HTTP client, or a generated SDK all work the same way.

Getting Started, Step by Step

From zero to your first API-created alias:

1. Be on Premium. API access is a Premium feature, so make sure your account is on the paid plan.
2. Open Settings → API Keys. In your dashboard, go to the API Keys section.
3. Create a key. Give it a name (so you can tell keys apart later) and generate it. Copy the ea_live_ value shown — this is your one chance to see it in full.
4. Store it safely. Put it in an environment variable or secrets manager, never in code you commit.
5. Make a request. Call the API with your key in the Authorization header (example below). Your first alias comes back in the response.

That’s the whole setup. You can create several keys (handy for separating projects or rotating credentials), and revoke any key from the same screen the moment you no longer need it — a revoked key stops working immediately.

A Working Example

Here’s the single most useful call — creating a new random alias — with cURL. Swap in your own key:

curl -X POST https://emailalias.io/api/aliases \
  -H "Authorization: Bearer ea_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"alias_type":"random","label":"newsletter"}'

The response comes back as JSON containing the new alias address, which you can immediately drop into a signup form or store against a customer record. To create a specific address instead of a random one, send "alias_type":"custom" with your chosen local part. Listing your aliases is a GET to the same /api/aliases endpoint, and removing one is a DELETE to /api/aliases/<id>. From those few calls you can build anything from a one-off cleanup script to a full integration — the same pattern EmailAlias’s own email forwarding API workflows follow.

AI Assistants and the MCP server

There’s a modern twist: EmailAlias ships an official MCP server, so AI assistants can manage your aliases through the same API. MCP (the Model Context Protocol) is the standard that lets AI tools call external services safely, and the @emailalias/mcp package plugs EmailAlias straight into assistants like Claude Desktop, Cursor, Zed, and Cline.

Setup is a one-liner — you run the MCP server with your ea_live_ key in an environment variable, and your assistant can then create an alias, list your addresses, or clean one up in response to a plain-language request. It’s the same account, the same key, and the same underlying calls; the MCP server just makes them available to an AI agent. For anyone who lives in an AI coding tool, it turns “make me a fresh alias for this signup” into something the assistant can just do.

OpenAPI Spec and SDKs

Because the API follows standards, you don’t have to hand-write a client. EmailAlias publishes an OpenAPI 3.1 specification, which describes the public API endpoints in a machine-readable form. That means:

• Auto-generated SDKs. Feed the spec to an OpenAPI generator and get a typed client in your language of choice — no manual wrapper needed.
• Live, accurate docs. The spec is generated from the API itself, so it always matches what the server actually accepts.
• Easy exploration. Point any OpenAPI-aware tool at the spec to browse and test endpoints interactively.

Between the spec, the developer documentation, and the MCP server, the API is built to be integrated quickly rather than reverse-engineered. Our write-up on the OpenAPI-driven email alias workflow goes deeper on generating clients from the spec.

Plan and Limits

• API access is Premium. Generating and using API keys is part of Premium ($4/month); free accounts don’t have API access.
• You can hold several keys. Premium accounts can keep multiple active keys — useful for separating projects or rotating credentials — and revoke any of them instantly.
• Normal account limits still apply. Calls through the API count against the same limits as the dashboard — for example the per-day alias-creation cap — so bulk creation is paced rather than unlimited. This protects deliverability for everyone on the shared domain.
• Keys can be rotated. If a key is ever exposed, revoke it and generate a new one; because keys are stored hashed, only you ever hold the full value.

What People Build With It

The API earns its keep wherever aliasing needs to be automatic:

• Per-account aliases in your product. A SaaS backend that gives every customer their own forwarding address, created automatically at signup.
• Automated signups. A script that registers accounts across services, minting a fresh alias for each so every signup is traceable and disposable.
• Bulk hygiene. A scheduled job that audits your aliases, flags dormant ones, and tidies up — using the list and delete calls.
• AI-driven aliasing. Through the MCP server, an assistant that creates and manages aliases as part of a larger workflow, on request.

If you’re weighing the API against other developer-friendly options, our roundup of the best email alias tools for developers puts it in context. The through-line is the same: anything you’d do by hand in the dashboard, the API lets you do at scale, on a schedule, or inside your own software.

Keeping Your API Keys Safe

An API key is a credential that can act on your account, so it deserves the same care as a password. A few habits keep it safe without getting in your way:

• Never hard-code a key. Keep it out of your source code and out of anything you commit to version control. Store it in an environment variable or a dedicated secrets manager, and read it from there at runtime.
• Use separate keys for separate jobs. Because you can hold several keys, give each project or environment its own. If one leaks, you revoke just that key without disrupting everything else.
• Rotate periodically. Generating a new key and retiring the old one every so often limits the damage a forgotten or exposed key could do.
• Revoke the moment you suspect exposure. A revoked key stops working immediately, so if a key ever ends up somewhere it shouldn’t, cut it off first and investigate second.

None of this is unique to EmailAlias — it’s ordinary API hygiene — but it’s worth stating, because the convenience of automation is only worth having if the key behind it is handled responsibly. The design helps here: keys are stored hashed and shown only once, so even EmailAlias never holds your key in a form that could be leaked back to you or anyone else. That leaves the one copy in your hands, and these habits keep that copy safe. Treat the key like the account credential it effectively is, and the API stays a convenience rather than a liability.

Final Thoughts

The email alias API takes EmailAlias from a tool you click to a service you can build on. It’s a plain REST API with Bearer-key auth, a published OpenAPI spec, and an MCP server for AI assistants — so whether you’re scripting a one-off task, embedding per-customer aliases in a product, or letting an agent handle it, the path is short: get a Premium key, send it in the Authorization header, and call /api/aliases. Everything the dashboard does becomes something your code can do too, which is exactly what you want from privacy infrastructure — the ability to make it automatic.

Frequently Asked Questions