How to export mail contacts in Exchange Online

Before you start

Use an account in a role group that can read recipients, such as View-Only Organization Management or Recipient Management. Microsoft lists the permissions for contacts under Recipients in its feature permissions for Exchange Online. The example uses the ExchangeOnlineManagement module and asks for no Microsoft Graph permission.

Know which recipient is which. A mail contact holds the details of someone outside your organisation, with an external email address. A mail user also has an external address, but it has sign-in credentials in your Microsoft 365 organisation and can reach its resources. The examples read and export; they create, change or remove no contact.

Option 1

Export mail contacts with PowerShell

Install the module once, then connect and export 1 row for each mail contact.

# Install once, if the module is not already installed.
Install-Module ExchangeOnlineManagement -Scope CurrentUser

$ErrorActionPreference = 'Stop'
Connect-ExchangeOnline
try {
    $contacts = @(Get-MailContact -ResultSize Unlimited)
    $report = @(foreach ($contact in $contacts) {
        $external = "$($contact.ExternalEmailAddress)" -replace '^SMTP:', ''
        [pscustomobject]@{
            Name = $contact.DisplayName
            ExternalAddress = $external
            ExternalDomain = ($external -split '@')[-1]
            PrimaryAddress = $contact.PrimarySmtpAddress
            Alias = $contact.Alias
            HiddenFromAddressLists = $contact.HiddenFromAddressListsEnabled
            Type = $contact.RecipientTypeDetails
        }
    })
    if ($report.Count -eq 0) {
        Write-Output 'The tenant has no mail contacts.'
    } else {
        $report | Sort-Object ExternalDomain, Name |
            Export-Csv -Path './mail-contacts.csv' -NoTypeInformation -Encoding utf8
        Write-Output "$($report.Count) mail contacts exported."
    }
} finally {
    Disconnect-ExchangeOnline -Confirm:$false
}

The CSV has 1 row per contact, sorted by the domain of its external address, so the contacts for each outside organisation sit together. The script takes the SMTP: prefix off the external address. Type is MailContact or MailForestContact, the 2 subtypes Get-MailContact returns. To keep only the contacts people can see in the address book, add -Filter 'HiddenFromAddressListsEnabled -eq $false'.

Add mail users and guests

Reconnect with Connect-ExchangeOnline, then read the mail users, guests included. The export above disconnects when it finishes.

# Run while connected to Exchange Online.
Get-MailUser -ResultSize Unlimited |
    Select-Object DisplayName, ExternalEmailAddress, PrimarySmtpAddress, RecipientTypeDetails

Option 2

Download the contacts list in the admin centre

1. Sign in to the Exchange admin centre for the correct tenant.
2. Go to Recipients > Contacts. The list shows Display name, Email address and Contact type for each entry.
3. Select Filter and choose Mail contacts to leave out mail users and guests.
4. Select every entry with the round check box in the column heading, then select Export contacts and Export contacts in current list.
5. Open Contacts.csv from your Downloads folder.

This suits a quick list of names and addresses. For more of each contact's settings, such as whether it is hidden from address lists or synced from on-premises, use PowerShell or a report.

Common questions

Why does my export stop at 1000 contacts?

Get-MailContact returns 1000 results by default. Add -ResultSize Unlimited, as the script does, to read every contact.

Why is a guest missing from the export?

A guest is a mail user, not a mail contact, so Get-MailContact leaves it out. Read guests with Get-MailUser, as in the second block. In the admin centre, the Contacts list has its own Guest mail users filter.

Which groups is a contact in?

A contact can be a member of distribution groups, so outside people receive the group's mail. To list every member of every group, contacts included, see how to export distribution group members in Exchange Online.