Working with Aliases

An alias is a tagged address on an existing inbox. Mail sent to ci+test-run-42@qa.acme.mailfork.dev is delivered to the ci inbox and tagged test-run-42. Aliases let you scope reads and OTP extractions to a single test run without creating separate inboxes.

Permanent vs Ephemeral

Permanent

Stays active until explicitly deleted or deactivated. Use for stable shared addresses — a password-reset alias that your whole team uses, or a shared address for a staging environment.

Ephemeral recommended for CI/CD

Has a TTL (time-to-live). Automatically deactivates on expiry. When onExpire: 'delete' is set, emails are moved to the Transient folder and purged after 24 hours — zero cleanup code needed.

Create a Permanent Alias

Via web UI: Open the inbox → Aliases → New Alias → enter a tag → Create.

Via SDK:

TypeScript

const alias = await mf.inboxes.createAlias({
  inbox: 'ci@qa.acme.mailfork.dev',
  tag: 'password-reset',
});

console.log(alias.address); // ci+password-reset@qa.acme.mailfork.dev

Create an Ephemeral Alias

Recommended CI pattern. Create a unique alias per test run — parallel runs won't bleed into each other. The alias auto-expires so you don't need any teardown code.

Via web UI: Open the inbox → Aliases → New Alias → check Ephemeral → set TTL hours → set onExpire (delete or archive) → Create.

Via SDK:

TypeScript

const alias = await mf.inboxes.createAlias({
  inbox: 'ci@qa.acme.mailfork.dev',
  tag: 'run-' + Date.now(),
  ttlHours: 1,
  onExpire: 'delete',
});

console.log(alias.address); // ci+run-1234567890@qa.acme.mailfork.dev

onExpire Behaviors

onExpire: 'delete'

When the alias expires, all emails tagged to it are moved to the Transient system folder. Emails in Transient are purged automatically after 24 hours. Nothing lingers in your inbox.

onExpire: 'archive'

The alias is deactivated (no longer accepts new mail) but all emails already delivered remain visible in the inbox under the alias tag. Useful for post-mortem debugging.

List and Deactivate Aliases

TypeScript

// List all aliases on an inbox
const aliases = await mf.inboxes.listAliases({
  inbox: 'ci@qa.acme.mailfork.dev',
});

// Deactivate a specific alias
await mf.inboxes.updateAlias({
  aliasId: aliases.items[0].id,
  isActive: false,
});

What's next?

CI/CD Integration →

Full GitHub Actions example using per-run ephemeral aliases.

OTP Extraction →

Scope OTP extraction to an alias tag for parallel-safe test runs.