WaymakerOS Help Center

Email aliases allow a single mailbox to receive email at multiple addresses across different domains. This is essential for domain migrations, company rebranding, or supporting multiple email identities.

What Are Email Aliases?

An email alias is an additional email address that delivers to an existing mailbox. Unlike email forwarding, the email is stored in the mailbox - not redirected elsewhere.

Example:

Primary mailbox: john@newcompany.com
Alias: john@oldcompany.com
Result: Emails to both addresses arrive in John's single mailbox

When to Use Email Aliases

Domain Migration / Rebrand

When your company changes domains (merger, rebrand, or consolidation):

Set up mailboxes on the new domain (@newcompany.com)
Add aliases from the old domain (@oldcompany.com)
Users receive email at both addresses in one inbox
Gradually transition external contacts to the new domain
Eventually retire the old domain aliases

Multiple Business Identities

When employees need to appear under multiple brands:

consultant@agencybrand.com (client-facing)
consultant@parentcompany.com (internal)

Simplified Addresses

Add short or memorable aliases:

Primary: john.smith@company.com
Alias: johns@company.com

Creating Email Aliases

Using the UI (Individual Aliases)

Navigate to WaymakerOne > Email > User Mailboxes
Click the menu (three dots) icon next to a user's mailbox
In the Email Aliases section, enter the alias local part
Select the domain from the dropdown (any verified domain)
Click the + button to add the alias

Using the CLI (Bulk Operations)

The CLI is ideal for bulk alias management during domain migrations.

Preview Alias Creation (Dry Run)

waymaker email aliases bulk-add \
  --domain <new-domain-id> \
  --source-domain <old-domain-id> \
  --dry-run

This shows what aliases would be created without making changes.

Execute Bulk Creation

waymaker email aliases bulk-add \
  --domain <new-domain-id> \
  --source-domain <old-domain-id> \
  --confirm

This creates aliases on the old domain that deliver to mailboxes on the new domain.

List Aliases for a Mailbox

waymaker email aliases list --mailbox <mailbox-id>

Bulk Operations for Domain Rebrand

Migration Workflow

Scenario: Migrating from oldcompany.com to newcompany.com

Get Domain IDs
```
waymaker domains list --json
```

Preview the Migration

waymaker email aliases bulk-add \
  --domain <newcompany-domain-id> \
  --dry-run

Execute the Migration

waymaker email aliases bulk-add \
  --domain <newcompany-domain-id> \
  --source-domain <oldcompany-domain-id> \
  --confirm

Verify Aliases Created

waymaker email aliases list --mailbox <any-mailbox-id>

Test Email Delivery
- Send test email to user@oldcompany.com
- Verify it arrives in the user@newcompany.com mailbox

Removing Aliases (Domain Retirement)

When you're ready to decommission the old domain:

# Preview removal
waymaker email aliases bulk-remove \
  --domain <old-domain-id> \
  --dry-run

# Execute removal
waymaker email aliases bulk-remove \
  --domain <old-domain-id> \
  --confirm

Warning: After removal, emails to the old addresses will bounce.

Email Aliases vs Email Forwarding

Feature	Email Aliases	Email Forwarding
Delivery	Same mailbox	Forward to external address
Storage	In the mailbox	No storage
Reply Address	Can reply as alias	N/A (no mailbox)
Use Case	Domain rebrand	Admin addresses
Management	WaymakerOne > User Mailboxes	WaymakerOne > Domains

Choose Email Aliases when:

Users need to receive email from old domains
You're migrating/rebranding domains
Users need multiple identities in one inbox

Choose Email Forwarding when:

You need administrative addresses (postmaster, abuse)
No mailbox should exist on the domain
Emails should go to external addresses

CLI Reference

See Email CLI Commands for complete command reference.

Quick Reference

# List aliases for a mailbox
waymaker email aliases list --mailbox <id> [--json]

# Bulk add aliases (preview)
waymaker email aliases bulk-add --domain <id> --dry-run

# Bulk add aliases (execute)
waymaker email aliases bulk-add --domain <id> [--source-domain <id>] --confirm

# Bulk remove aliases (preview)
waymaker email aliases bulk-remove --domain <id> --dry-run

# Bulk remove aliases (execute)
waymaker email aliases bulk-remove --domain <id> --confirm

Best Practices

Always preview first - Use --dry-run before bulk operations
Keep old aliases active - Don't remove until you're sure all contacts have updated
Communicate the change - Notify external contacts of new email addresses
Update email signatures - Ensure users update their signatures to the new domain
Test before going live - Verify email delivery works as expected

Troubleshooting

Alias Not Receiving Email

Verify the alias was created: waymaker email aliases list --mailbox <id>
Check the source domain is still verified
Ensure DNS records for the old domain are still active

"Address Already Exists" Error

The alias address conflicts with:

An existing mailbox
Another alias
A forwarding alias

Check both domains for conflicts.

Bulk Operation Skipping Mailboxes

The bulk add operation only creates aliases for:

Active mailboxes on the target domain
Mailboxes where the alias doesn't already exist

Check the operation output for "Skipped" entries.

Email Aliases for Domain Rebrand