Guide 3 of 8
Working with Aliases
An alias is a tagged address on an existing inbox. Mail sent to
[email protected]
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:
const alias = await mf.inboxes.createAlias({
inbox: '[email protected]',
tag: 'password-reset',
});
console.log(alias.address); // [email protected]Create an Ephemeral Alias
Via web UI: Open the inbox → Aliases → New Alias → check Ephemeral → set TTL hours → set onExpire (delete or archive) → Create.
Via SDK:
const alias = await mf.inboxes.createAlias({
inbox: '[email protected]',
tag: 'run-' + Date.now(),
ttlHours: 1,
onExpire: 'delete',
});
console.log(alias.address); // [email protected]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
// List all aliases on an inbox
const aliases = await mf.inboxes.listAliases({
inbox: '[email protected]',
});
// Deactivate a specific alias
await mf.inboxes.updateAlias({
aliasId: aliases.items[0].id,
isActive: false,
});