emailalias-nodejs

Official Node.js client for the EmailAlias.io REST API. TypeScript types included.

API access is a Premium feature. Generate a key from Settings → API Keys in the web dashboard.

Install

npm install emailalias
# or
yarn add emailalias
# or
pnpm add emailalias

Requires Node.js 18+ (uses the global fetch).

Quick start

import { Client } from "emailalias";

const client = new Client({
  apiKey: process.env.EMAILALIAS_API_KEY!,
});

// Create an alias
const alias = await client.createAlias({
  alias_type: "random",
  label: "Shopping",
});
console.log(alias.alias_email); // "[email protected]"

// List aliases
const aliases = await client.listAliases();
aliases.forEach((a) => console.log(a.alias_email, "→", a.destination_email));

// Forward to a verified additional destination
const workAlias = await client.createAlias({
  alias_type: "custom",
  custom_code: "work-signup",
  label: "Work",
  destination_email: "[email protected]", // must be verified on your account
});

// Send email from an alias
await client.sendEmail({
  alias_id: alias.id,
  to_email: "[email protected]",
  subject: "Hello",
  body: "Sent from my alias.",
});

// Disable an alias
await client.updateAlias(alias.id, { active: false });

Error handling

import {
  Client,
  AuthenticationError,
  RateLimitError,
  EmailAliasError,
} from "emailalias";

const client = new Client({ apiKey: "ea_live_xxx" });

try {
  await client.listAliases();
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid key, or account no longer Premium
  } else if (err instanceof RateLimitError) {
    // Respect X-RateLimit-Reset and retry
  } else if (err instanceof EmailAliasError) {
    console.error(err.status, err.message);
  }
}

Configuration

const client = new Client({
  apiKey: "ea_live_xxx",
  baseUrl: "https://emailalias.io", // override for staging / self-host
  timeoutMs: 30_000,
  fetchImpl: fetch, // inject a custom fetch (e.g. `undici`)
});

⚠️ Browser usage

Never put a live API key in frontend code. Any user can open devtools and read it. If you're building a browser/React app, call EmailAlias.io from your backend and proxy requests from the client, or use emailalias-react from a Next.js Route Handler / server action.

Available methods

| Method | Endpoint | |---|---| | listAliases() | GET /api/aliases | | createAlias(opts) | POST /api/aliases | | updateAlias(id, opts) | PATCH /api/aliases/{id} | | updateAliasDisplayName(id, displayName) | PATCH /api/aliases/{id}/display-name | | deleteAlias(id) | DELETE /api/aliases/{id} | | listAvailableDomains() | GET /api/aliases/domains | | listDestinations() | GET /api/destinations | | addDestination(email) | POST /api/destinations | | resendDestinationVerification(id) | POST /api/destinations/{id}/resend | | deleteDestination(id) | DELETE /api/destinations/{id} | | sendEmail({alias_id, to_email, subject, body, html_body?}) | POST /api/send-email | | listDomains() | GET /api/domains | | addDomain(name) | POST /api/domains | | verifyDomain(id) | POST /api/domains/{id}/verify | | deleteDomain(id) | DELETE /api/domains/{id} | | getDashboardStats() | GET /api/analytics/dashboard | | listLogs(page, perPage) | GET /api/analytics/logs | | listExposureEvents(page, perPage) | GET /api/analytics/exposure |

Full API reference: https://emailalias.io/documentation

License

MIT