Manage mail users in Exchange Online

In Exchange Online organizations, mail users are similar to mail contacts. Both have external email addresses and both contain information about people outside your Exchange Online organization that can be displayed in the shared address book and other address lists. However, unlike a mail contact, a mail user has sign in credentials in your Microsoft 365 organization and can access resources. For more information about mail contacts and mail users, see Recipients in Exchange Online.

You manage mail users in the Exchange admin center (EAC) or in PowerShell (Exchange Online PowerShell in organizations with Exchange Online mailboxes).

What do you need to know before you begin?

Use the Exchange admin center to manage mail users

Use the EAC to create mail users

  1. In the EAC, click Recipients > Contacts.

  2. Click Add a mail contact and configure the following settings in the details pane. Settings marked with an * are required.

    • Basic information

      • Contact type: Select Mail user from the drop-down list.
      • First name
      • Last name
      • *Display name: By default, this box shows the values from the First name, and Last name boxes. You can accept this value or change it.
      • *External email address: Enter the user's email address. The domain should be external to your cloud-based organization.
      • *Alias: Enter a unique alias, using up to 64 characters for the user.
      • *User ID and Domain: Enter the account that the person will use to sign in to the service. The user ID consists of a username on the left side of the at (@) symbol and a domain on the right side. Select the domain from the drop-down list.
      • Password
      • Confirm password
    • Mail contact information (Optional)

    • Review mail user

  3. When you're finished, click Create.

Use the EAC to modify mail users

  1. In the EAC, click Recipients > Contacts.

  2. In the list of users, select the mail user by clicking anywhere in the row other than the button option that appears in the blank area next to the Display name column.

  3. In the details flyout that opens, view or edit the user's details.

  4. When you're finished, click Save.

The contacts details flyout has the following sections:

  • General

    • First name
    • Last name
    • Display name
    • External email address
  • Personal information: This section has Contact information and Organization information.

Use the Contact information section, to view, or edit the user's information. The information on this page is displayed in the address book.

  • Web site
  • Fax phone
  • Home phone
  • Mobile phone
  • Work phone
  • Office
  • Street
  • City
  • State/Province
  • ZIP/Postal code
  • Country/Region

Use the Organization section, to record detailed information about the user's role in the organization. This information is displayed in the address book. Also, you can create a virtual organization chart that's accessible from email clients such as Outlook.

  • Title: Use this box to view or change the recipient's title.

  • Department: Use this box to view or change the department in which the user works. You can use this box to create recipient conditions for dynamic distribution groups, email address policies, or address lists.

  • Manager: To add a manager, enter the name and select from the drop-down list.

  • Direct reports: You can't modify this box. A direct report is a user who reports to a specific manager. If you've specified a manager for the user, that user appears as a direct report in the details of the manager's mailbox. For example, Kari manages Chris and Kate, so Kari is specified in the Manager box for Chris and Kate, and Chris and Kate appear in the Direct reports box in the properties of Kari's account.

  • Others

    • Custom attributes
    • Member of (Group membership)
    • Email addresses
    • Message delivery restrictions

Use the EAC to remove mail users

  1. In the EAC, click Recipients > Contacts.

  2. Select the mail user that you want to remove, and then click Delete.


    EAC doesn't allow bulk edit of mail users yet.

Use PowerShell to manage mail users

In Exchange Online PowerShell, you use the following cmdlets to manage mail users:

Use Exchange Online PowerShell to create mail users

This example creates a mail user for Rene Valdes:

  • The name and display name is Rene Valdes (if you don't use the DisplayName parameter, the value of the Name parameter is used for the display name).
  • The alias is renev.
  • The external email address is
  • The sign in name is
  • The password is Pa$$word1.
New-MailUser -Name "Rene Valdes" -Alias renev -ExternalEmailAddress -FirstName Rene -LastName Valdes -MicrosoftOnlineServicesID -Password (ConvertTo-SecureString -String 'P@ssw0rd' -AsPlainText -Force)

For detailed syntax and parameter information, see New-MailUser.

Use Exchange Online PowerShell to modify mail users

In general, use the Get-User and Set-User cmdlets to view and change organization and contact information properties. Use the Get-MailUser and Set-MailUser cmdlets to view or change mail-related properties, such as email addresses, the MailTip, custom attributes, and whether the mail user is hidden from address lists.

Use the Get-MailUser and Set-MailUser cmdlets to view and change properties for mail users. For information, see the following articles:

Here are some examples of using Exchange Online PowerShell to change mail user properties.

This example sets the external email address for Pilar Pinilla.

Set-MailUser "Pilar Pinilla" -ExternalEmailAddress

This example hides all mail users from the organization's address book.

$MEU = Get-MailUser -ResultSize unlimited
$MEU | foreach {Set-MailUser -Identity $_ -HiddenFromAddressListsEnabled $true}

This example sets the Company property for all mail users to Contoso.

$U = Get-User -ResultSize unlimited -Filter "RecipientTypeDetails -eq 'mailuser'"
$U | foreach {Set-User -Identity $_ -Company Contoso}

This example sets the CustomAttribute1 property to a value of ContosoEmployee for all mail users that have a value of Contoso in the Company property.

$Contoso = Get-User -ResultSize unlimited -Filter "(RecipientTypeDetails -eq 'mailuser') -and (Company -eq 'Contoso')"
$Contoso | foreach {Set-MailUser -Identity $_ -CustomAttribute1 ContosoEmployee}

Use Exchange Online PowerShell to remove mail users

To remove a mail user, use the following syntax:

Remove-MailUser -Identity <MailUserIdentity>

This example removes the mail user for Pilar Pinilla:

Remove-MailUser -Identity "Pilar Pinilla"

For detailed syntax and parameter information, see Remove-MailUser

How do you know these procedures worked?

To verify that you've successfully created, modified, or removed mail users, do any of the following steps:

  • In the EAC, click Recipients > Contacts. Verify the mail user is listed (or not listed). The Contact Type value is MailUser. Select the mail contact from the list, by clicking anywhere in the row other than the button option that appears in the blank area next to the Display name column to view or edit the user's details.

  • In Exchange Online PowerShell, replace <MailUserIdentity> with the name, email address, or alias of the mail user, and run the following command to verify that the mail user is listed (or not listed).

    Get-MailUser -Identity <MailUserIdentity> | Format-List Name,Alias,DisplayName,ExternalEmailAddress
  • In Exchange Online PowerShell, use the Get-User and Get-MailUser cmdlets to verify the property changes you made.

    Get-MailUser | Format-List Name,CustomAttribute1
    Get-User -ResultSize unlimited -Filter "RecipientTypeDetails -eq 'mailuser'" | Format-List Name,Company

Use directory synchronization to manage mail users

In Exchange Online, directory synchronization is available for hybrid customers with on-premises and cloud-hosted mailboxes, and for fully hosted Exchange Online customers whose Active Directory is on-premises.

In standalone EOP, directory synchronization is available for customers with on-premises Active Directory.


  • If you use directory synchronization to manage your recipients, you can still add and manage users in the Microsoft 365 admin center, but they will not be synchronized with your on-premises Active Directory. This is because directory synchronization only syncs recipients from your on-premises Active Directory to the cloud.

  • Using directory synchronization is recommended for use with the following features:

    • Outlook Safe Sender lists and Blocked Sender lists: When synchronized to the service, these lists will take precedence over spam filtering in the service. This lets users manage their own Safe Sender list and Blocked Sender list with individual sender and domain entries. For more information, see Configure junk email settings on Exchange Online mailboxes.
    • Directory Based Edge Blocking (DBEB): For more information about DBEB, see Use Directory Based Edge Blocking to reject messages sent to invalid recipients.
    • End user access to quarantine: To access their quarantined messages, recipients must have a valid user ID and password in the service. For more information about quarantine, see Find and release quarantined messages as a user.
    • Mail flow rules (also known as transport rules): When you use directory synchronization, your existing Active Directory users and groups are automatically uploaded to the cloud, and you can then create mail flow rules that target specific users and/or groups without having to manually add them in the service. Note that dynamic distribution groups can't be synchronized via directory synchronization.

Get the necessary permissions and prepare for directory synchronization, as described in What is Microsoft Entra Connect?.

Synchronize directories with Microsoft Entra Connect

  1. Activate directory synchronization as described in Microsoft Entra Connect Sync: Understand and customize synchronization.

  2. Install and configure an on-premises computer to run Microsoft Entra Connect as described in Prerequisites for Microsoft Entra Connect.

  3. Select which installation type to use for Microsoft Entra Connect:


When you finish the Azure Active Directory Sync Tool Configuration Wizard, the MSOL_AD_SYNC account is created in your Active Directory forest. This account is used to read and synchronize your on-premises Active Directory information. In order for directory synchronization to work correctly, make sure that TCP 443 on your local directory synchronization server is open.

After configuring your sync, be sure to verify that Microsoft Entra Connect is synchronizing correctly. In the EAC, click Recipients > Contacts and view the list of users was correctly synchronized from your on-premises environment.