Skip to content
exonaut

mailContacts

Mail Contacts. External contacts that appear in the address book. The mailContacts entity set lives under /exchange/v1.0/mailContacts in the Recipients category.

Fact Value
Path /exchange/v1.0/mailContacts
Category Recipients
Tier Tier 0, Directory
Read role Recipient.Read.All (Community)
Write role Recipient.ReadWrite.All (Pro)
Backing cmdlets Get-MailContact, Set-MailContact, New-MailContact, Remove-MailContact

Routes

Section titled “Routes”
Method Path Synopsis Role Plan
GET /exchange/v1.0/mailContacts List mailContacts entries. Recipient.Read Community
POST /exchange/v1.0/mailContacts POST /mailContacts - creates an external mail recipient via New-MailContact. name + externalEmailAddress required. Returns 201 + Location. Recipient.ReadWrite Pro
GET /exchange/v1.0/mailContacts/{key} Get a single mailContacts entry by Identity. Recipient.Read Community
PATCH /exchange/v1.0/mailContacts/{key} PATCH /mailContacts/{key} - partial update via Set-MailContact. Returns 200 + updated entity. Recipient.ReadWrite Pro
DELETE /exchange/v1.0/mailContacts/{key} DELETE /mailContacts/{key} - destructive. Recipient.ReadWrite Pro

GET /exchange/v1.0/mailContacts

Section titled “GET /exchange/v1.0/mailContacts”

List mailContacts entries.

Backing cmdlet: Get-MailContact. Role: Recipient.Read (Community).

Parameter In Type Required Description
all query bool (switch) Return all results instead of the EXO default of 1000. Maps -ResultSize Unlimited on Get-MailContact; prevents silent truncation in large tenants.
anr query string Ambiguous name resolution search string. Maps -ANR on Get-MailContact.
recipientTypeDetails query string Filter by mail-contact subtype (MailContact, MailForestContact). Comma-separated. Maps -RecipientTypeDetails on Get-MailContact.
organizationalUnit query string Filter by the object’s OU/domain location. Maps -OrganizationalUnit on Get-MailContact.

List mailContacts

Section titled “List mailContacts”

Stub auto-generated example for the mailContacts collection. Backing cmdlet: Get-MailContact. Live-verify with ?$top=3&$select=Id,Name and replace the synthetic body before promoting to Tier 1.

GET /exchange/v1.0/mailContacts?$top=3 HTTP/1.1
Authorization: Bearer {token}
HTTP/1.1 200 OK


{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#mailContacts",
  "value": []
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

Related: GET /exchange/v1.0/mailContacts/{key}

POST /exchange/v1.0/mailContacts

Section titled “POST /exchange/v1.0/mailContacts”

POST /mailContacts - creates an external mail recipient via New-MailContact. name + externalEmailAddress required. Returns 201 + Location.

Backing cmdlet: New-MailContact. Role: Recipient.ReadWrite (Pro).

Parameter In Type Required Description
externalEmailAddress body yes
name body yes
alias body
displayName body
firstName body
initials body
lastName body
macAttachmentFormat body
messageBodyFormat body
messageFormat body
moderatedBy body
moderationEnabled body
organizationalUnit body
sendModerationNotifications body
usePreferMessageFormat body
dryRun query bool (switch)

Create mail contact rejected for missing required field

Section titled “Create mail contact rejected for missing required field”

New-MailContact requires both name and externalEmailAddress. Omitting externalEmailAddress fails body validation before the cmdlet runs and returns the canonical 400 envelope.

POST /exchange/v1.0/mailContacts HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json


{
  "name": "exonaut-sample-mailContacts"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json


{
  "error": {
    "code": "BadRequest",
    "message": "The required field 'externalEmailAddress' is missing or empty.",
    "target": "externalEmailAddress"
  },
  "correlationId": "0HN7EXONAUT0SAMPLE0MAILCONTACTS"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/mailContacts

Create an external mail contact

Section titled “Create an external mail contact”

Creates an external mail recipient (no Entra principal) via New-MailContact. Both name and externalEmailAddress are required; the contact becomes routable in Exchange address lists.

POST /exchange/v1.0/mailContacts HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json


{
  "name": "exonaut-sample-mailContacts",
  "externalEmailAddress": "vendor.contact@contoso.com",
  "alias": "exonaut-sample-mailContacts",
  "displayName": "Exonaut Sample Contact",
  "firstName": "Exonaut",
  "lastName": "Contact"
}
HTTP/1.1 201 Created
Location: /exchange/v1.0/mailContacts/exonaut-sample-mailContacts


{
  "Id": "exonaut-sample-mailContacts",
  "Identity": "exonaut-sample-mailContacts",
  "Name": "exonaut-sample-mailContacts",
  "DisplayName": "Exonaut Sample Contact",
  "Alias": "exonaut-sample-mailContacts",
  "ExternalEmailAddress": "SMTP:vendor.contact@contoso.com",
  "PrimarySmtpAddress": "vendor.contact@contoso.com",
  "RecipientType": "MailContact",
  "RecipientTypeDetails": "MailContact"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/mailContacts

GET /exchange/v1.0/mailContacts/{key}

Section titled “GET /exchange/v1.0/mailContacts/{key}”

Get a single mailContacts entry by Identity.

Backing cmdlet: Get-MailContact. Role: Recipient.Read (Community).

Get a single mailContacts entry

Section titled “Get a single mailContacts entry”

Stub auto-generated example for GET /mailContacts/{key}. Backing cmdlet: Get-MailContact with -Identity {key}. Returns the full entity body; 404 if the identity doesn’t resolve.

GET /exchange/v1.0/mailContacts/{key} HTTP/1.1
Authorization: Bearer {token}
HTTP/1.1 200 OK


{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#mailContacts/$entity"
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

Related: GET /exchange/v1.0/mailContacts

PATCH /exchange/v1.0/mailContacts/{key}

Section titled “PATCH /exchange/v1.0/mailContacts/{key}”

PATCH /mailContacts/{key} - partial update via Set-MailContact. Returns 200 + updated entity.

Backing cmdlet: Set-MailContact. Role: Recipient.ReadWrite (Pro).

Parameter In Type Required Description
acceptMessagesOnlyFrom body
acceptMessagesOnlyFromDLMembers body
acceptMessagesOnlyFromSendersOrMembers body
alias body
arbitrationMailbox body
bypassModerationFromSendersOrMembers body
createDTMFMap body
customAttribute1 body
customAttribute10 body
customAttribute11 body
customAttribute12 body
customAttribute13 body
customAttribute14 body
customAttribute15 body
customAttribute2 body
customAttribute3 body
customAttribute4 body
customAttribute5 body
customAttribute6 body
customAttribute7 body
customAttribute8 body
customAttribute9 body
displayName body
emailAddresses body
emailAddressPolicyEnabled body
extensionCustomAttribute1 body
extensionCustomAttribute2 body
extensionCustomAttribute3 body
extensionCustomAttribute4 body
extensionCustomAttribute5 body
externalEmailAddress body
grantSendOnBehalfTo body
hiddenFromAddressListsEnabled body
macAttachmentFormat body
mailTip body
mailTipTranslations body
maxReceiveSize body
maxRecipientPerMessage body
maxSendSize body
messageBodyFormat body
messageFormat body
moderatedBy body
moderationEnabled body
name body
primarySmtpAddress body
rejectMessagesFrom body
rejectMessagesFromDLMembers body
rejectMessagesFromSendersOrMembers body
removePicture body boolean (switch)
removeSpokenName body boolean (switch)
requireSenderAuthenticationEnabled body
secondaryAddress body
secondaryDialPlan body
sendModerationNotifications body
simpleDisplayName body
umDtmfMap body
useMapiRichTextFormat body
usePreferMessageFormat body
userCertificate body
userSMimeCertificate body
windowsEmailAddress body
dryRun query bool (switch)

Update a mail contact

Section titled “Update a mail contact”

Partial update of an external mail contact via Set-MailContact. Only the supplied SetWritable fields are changed; the updated entity is returned.

PATCH /exchange/v1.0/mailContacts/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json


{
  "displayName": "Exonaut Sample Contact (Updated)",
  "mailTip": "External vendor contact - route via partner mailbox.",
  "hiddenFromAddressListsEnabled": true
}
HTTP/1.1 200 OK
Content-Type: application/json


{
  "Id": "exonaut-sample-mailContacts",
  "Identity": "exonaut-sample-mailContacts",
  "Name": "exonaut-sample-mailContacts",
  "DisplayName": "Exonaut Sample Contact (Updated)",
  "ExternalEmailAddress": "SMTP:vendor.contact@contoso.com",
  "PrimarySmtpAddress": "vendor.contact@contoso.com",
  "MailTip": "External vendor contact - route via partner mailbox.",
  "HiddenFromAddressListsEnabled": true,
  "RecipientType": "MailContact",
  "RecipientTypeDetails": "MailContact"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/mailContacts

DELETE /exchange/v1.0/mailContacts/{key}

Section titled “DELETE /exchange/v1.0/mailContacts/{key}”

DELETE /mailContacts/{key} - destructive.

Backing cmdlet: Remove-MailContact. Role: Recipient.ReadWrite (Pro).

Parameter In Type Required Description
dryRun query bool (switch)

Delete a mail contact

Section titled “Delete a mail contact”

Destructively removes an external mail contact via Remove-MailContact. Returns 204 No Content on success.

DELETE /exchange/v1.0/mailContacts/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/mailContacts

?dryRun=true previews of any write stay on Community.