Add an Email Alias (Proxy Address) to a Mailbox via Microsoft Graph

Add an alias using the Microsoft 365 admin center

1. Sign in to the Microsoft 365 admin center as a Global Administrator, User Administrator, or Exchange Administrator.
2. Navigate to Users → Active users (for a regular user mailbox) or Teams & groups → Shared mailboxes (for a shared mailbox).
3. Click the display name of the mailbox you want to modify (for example, info@contoso.com).
4. In the flyout, select the Mail tab, then click Manage email aliases.
5. In the Alias field, type the local part of the new alias (e.g. dex), then choose the verified domain from the dropdown (e.g. contoso.com). Click Add.
6. Click Save changes. The alias appears in the list with the label Alias; the address marked Primary remains unchanged.
7. Wait 5–10 minutes for directory propagation, then send a test message to the new alias to confirm delivery.

Shared mailboxes (Exchange admin center)

1. Go to the Exchange admin center.
2. Select Recipients → Mailboxes and open the target mailbox.
3. Under General → Manage email address types, click + Add email address type, choose SMTP, enter the alias, and save.

Add an alias using Microsoft Graph

Aliases are managed as the proxyAddresses property on the user resource. Because proxyAddresses is a collection, a PATCH replaces the full list — so you must first read the existing values, append the new one, and write the combined list back.

Step 1 — Read the current proxy addresses

GET https://graph.microsoft.com/v1.0/users/{mailbox-upn}?$select=id,displayName,userPrincipalName,proxyAddresses

Example response:

{
  "id": "6a6900a9-c0a6-4d0c-8e4f-5fe437f6b460",
  "displayName": "Info",
  "userPrincipalName": "info@contoso.com",
  "proxyAddresses": [
    "SMTP:info@contoso.com"
  ]
}

Step 2 — Check whether the alias already exists

Compare case-insensitively against the existing entries. If smtp:dex@contoso.com or SMTP:dex@contoso.com is already present, stop — no action is required.

Step 3 — PATCH the user with the combined list

PATCH https://graph.microsoft.com/v1.0/users/{mailbox-upn}
Content-Type: application/json

{
  "proxyAddresses": [
    "SMTP:info@contoso.com",
    "smtp:dex@contoso.com"
  ]
}

A successful request returns 204 No Content.

Step 4 — Verify

Re-run the GET from Step 1 and confirm the new smtp: entry is present and the uppercase SMTP: primary is unchanged.

Common errors

Add an alias using PowerShell

You have two good options depending on what's installed:

Option A — Microsoft Graph PowerShell SDK (recommended)

Install once:

Install-Module Microsoft.Graph -Scope CurrentUser

Then:

Connect-MgGraph -Scopes "User.ReadWrite.All"

# Read current proxyAddresses
$mailbox   = "info@contoso.com"
$newAlias  = "dex@contoso.com"
$user = Get-MgUser -UserId $mailbox -Property Id,ProxyAddresses
$existing = @($user.ProxyAddresses)

# Skip if already present (case-insensitive on the address part)
if ($existing -match "^smtp:$([regex]::Escape($newAlias))$") {
    Write-Host "Alias already exists — no change."
    return
}

$updated = $existing + "smtp:$newAlias"
Update-MgUser -UserId $user.Id -ProxyAddresses $updated

Option B — Exchange Online PowerShell

If you prefer the Exchange cmdlets:

Install-Module ExchangeOnlineManagement -Scope CurrentUser
Connect-ExchangeOnline

Set-Mailbox -Identity "info@contoso.com" `
            -EmailAddresses @{Add="smtp:dex@contoso.com"}

The @{Add=...} hashtable syntax adds to the existing list without replacing it — safer than passing a full array.

Verify

Get-MgUser -UserId "info@contoso.com" -Property ProxyAddresses |
    Select-Object -ExpandProperty ProxyAddresses