Guide 3 of 8
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.
Auto-Created Aliases
Aliases can be automatically created when an email arrives at a tagged address that doesn't yet exist.
For example, if you send an email to ci+approver@qa.acme.mailfork.dev
and the approver tag doesn't exist, MailFork
automatically creates an ephemeral alias for it.
Example
SalesApp+Approver@qa.acme.mailfork.dev
An email sent to this address creates an ephemeral alias tagged Approver automatically — no explicit creation needed.
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 received on that alias are immediately deleted on expiry — 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: 'ci@qa.acme.mailfork.dev',
tag: 'password-reset',
});
console.log(alias.address); // ci+password-reset@qa.acme.mailfork.devCreate 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: 'ci@qa.acme.mailfork.dev',
tag: 'run-' + Date.now(),
ttlHours: 1,
onExpire: 'delete',
});
console.log(alias.address); // ci+run-1234567890@qa.acme.mailfork.devonExpire Behaviors
onExpire: 'delete'
When the alias expires, all emails tagged to it are immediately and permanently deleted. Nothing lingers in your inbox.
onExpire: 'keep'
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: 'ci@qa.acme.mailfork.dev',
});
// Deactivate a specific alias
await mf.inboxes.updateAlias({
aliasId: aliases.items[0].id,
isActive: false,
});