remoteDomains

Remote Domains. Control mail formatting and behavior toward specific external domains. The remoteDomains entity set lives under /exchange/v1.0/remoteDomains in the Mail flow category.

Fact	Value
Path	/exchange/v1.0/remoteDomains
Category	Mail flow
Tier	Tier 3, Mail flow
Read role	MailFlow.Read.All (Community)
Write role	MailFlow.ReadWrite.All (Pro)
Backing cmdlets	Get-RemoteDomain, Set-RemoteDomain, New-RemoteDomain, Remove-RemoteDomain

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/remoteDomains	List remoteDomains entries.	MailFlow.Read	Community
POST	/exchange/v1.0/remoteDomains	POST /remoteDomains - creates a remote-domain config via New-RemoteDomain. Returns 201 + Location.	MailFlow.ReadWrite	Pro
GET	/exchange/v1.0/remoteDomains/{key}	Get a single remoteDomains entry by Identity.	MailFlow.Read	Community
PATCH	/exchange/v1.0/remoteDomains/{key}	PATCH /remoteDomains/{key} - partial update via Set-RemoteDomain. Returns 200 + updated entity.	MailFlow.ReadWrite	Pro
DELETE	/exchange/v1.0/remoteDomains/{key}	DELETE /remoteDomains/{key} - removes the remote-domain config. The built-in “Default” entry cannot be removed.	MailFlow.ReadWrite	Pro

GET /exchange/v1.0/remoteDomains

List remoteDomains entries.

Backing cmdlet: Get-RemoteDomain. Role: MailFlow.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-RemoteDomain; prevents silent truncation in large tenants.

List remote domains

Returns the configured remote domains for the tenant, backed by Get-RemoteDomain. Each entry controls message-format and out-of-office behavior for mail sent to that external domain.

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

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#remoteDomains",
  "value": [
    {
      "Id": "Default",
      "Name": "Default",
      "Identity": "Default",
      "DistinguishedName": "CN=Default,CN=Internet Message Formats,CN=Global Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
      "AdminDisplayName": "",
      "Guid": "9f2c1a47-3b8e-4d12-a6f0-77c5e90b2d31",
      "DomainName": "*",
      "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
      "IsInternal": false,
      "AutoReplyEnabled": true,
      "AutoForwardEnabled": true,
      "AllowedOOFType": "External",
      "DeliveryReportEnabled": true,
      "NDREnabled": true,
      "NDRDiagnosticInfoEnabled": true,
      "MeetingForwardNotificationEnabled": false,
      "MessageCountThreshold": 2147483647,
      "ContentType": "MimeHtmlText",
      "CharacterSet": "iso-8859-1",
      "NonMimeCharacterSet": "iso-8859-1",
      "ByteEncoderTypeFor7BitCharsets": "Undefined",
      "RequiredCharsetCoverage": null,
      "LineWrapSize": "Unlimited",
      "DisplaySenderName": true,
      "TNEFEnabled": false,
      "PreferredInternetCodePageForShiftJis": "Undefined",
      "TargetDeliveryDomain": "False",
      "TrustedMailInboundEnabled": "False",
      "TrustedMailOutboundEnabled": "False",
      "UseSimpleDisplayName": "False",
      "WhenCreated": "2026-03-30T17:02:19+03:00",
      "WhenChanged": "2026-03-30T17:02:30+03:00",
      "WhenCreatedUTC": "2026-03-30T17:02:19+03:00",
      "WhenChangedUTC": "2026-03-30T17:02:30+03:00",
      "ExchangeObjectId": "b3d80451-2e7c-4a9d-9f31-c0481de52aa8",
      "OrganizationalUnitRoot": "contoso.onmicrosoft.com"
    }
  ]
}

Notes: The tenant ships with a single built-in Default remote domain (DomainName “*”) that applies to all external domains until you add domain-specific entries.

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

POST /exchange/v1.0/remoteDomains

POST /remoteDomains - creates a remote-domain config via New-RemoteDomain. Returns 201 + Location.

Backing cmdlet: New-RemoteDomain. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
domainName	body		yes
name	body		yes
dryRun	query	bool (switch)

Create fails when a required field is missing

New-RemoteDomain requires both Name and DomainName. Omitting DomainName produces a 400 BadRequest from the request-body validation before the cmdlet runs.

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

{
  "name": "exonaut-sample-remoteDomains"
}

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "BadRequest",
    "message": "The field 'domainName' is required.",
    "target": "domainName"
  },
  "correlationId": "0HN7K2P9QF3X1:00000007"
}

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

Related: GET /exchange/v1.0/remoteDomains

Create a remote-domain configuration

Creates a remote-domain config via New-RemoteDomain. Both Name (the entry’s friendly identity) and DomainName (the DNS domain it applies to) are required. Returns 201 with a Location header.

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

{
  "name": "exonaut-sample-remoteDomains",
  "domainName": "contoso.com"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/remoteDomains/exonaut-sample-remoteDomains

{
  "Id": "exonaut-sample-remoteDomains",
  "Identity": "exonaut-sample-remoteDomains",
  "Name": "exonaut-sample-remoteDomains",
  "DomainName": "contoso.com"
}

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

Related: GET /exchange/v1.0/remoteDomains

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

Get a single remoteDomains entry by Identity.

Backing cmdlet: Get-RemoteDomain. Role: MailFlow.Read (Community).

Get a single remoteDomains entry

Returns one remote domain by identity, backed by Get-RemoteDomain with -Identity {key}. The full entity body includes the message-format, out-of-office, and delivery-report settings for that domain.

GET /exchange/v1.0/remoteDomains/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#remoteDomains/$entity",
  "Id": "Default",
  "Name": "Default",
  "Identity": "Default",
  "DistinguishedName": "CN=Default,CN=Internet Message Formats,CN=Global Settings,CN=Configuration,CN=contoso.onmicrosoft.com,CN=ConfigurationUnits,DC=EURPR01A017,DC=PROD,DC=OUTLOOK,DC=COM",
  "AdminDisplayName": "",
  "Guid": "9f2c1a47-3b8e-4d12-a6f0-77c5e90b2d31",
  "DomainName": "*",
  "OrganizationId": "EURPR01A017.PROD.OUTLOOK.COM/Microsoft Exchange Hosted Organizations/contoso.onmicrosoft.com - EURPR01A017.PROD.OUTLOOK.COM/ConfigurationUnits/contoso.onmicrosoft.com/Configuration",
  "IsInternal": false,
  "AutoReplyEnabled": true,
  "AutoForwardEnabled": true,
  "AllowedOOFType": "External",
  "DeliveryReportEnabled": true,
  "NDREnabled": true,
  "NDRDiagnosticInfoEnabled": true,
  "MeetingForwardNotificationEnabled": false,
  "MessageCountThreshold": 2147483647,
  "ContentType": "MimeHtmlText",
  "CharacterSet": "iso-8859-1",
  "NonMimeCharacterSet": "iso-8859-1",
  "ByteEncoderTypeFor7BitCharsets": "Undefined",
  "RequiredCharsetCoverage": null,
  "LineWrapSize": "Unlimited",
  "DisplaySenderName": true,
  "TNEFEnabled": false,
  "PreferredInternetCodePageForShiftJis": "Undefined",
  "TargetDeliveryDomain": "False",
  "TrustedMailInboundEnabled": "False",
  "TrustedMailOutboundEnabled": "False",
  "UseSimpleDisplayName": "False",
  "WhenCreated": "2026-03-30T17:02:19+03:00",
  "WhenChanged": "2026-03-30T17:02:30+03:00",
  "WhenCreatedUTC": "2026-03-30T17:02:19+03:00",
  "WhenChangedUTC": "2026-03-30T17:02:30+03:00",
  "ExchangeObjectId": "b3d80451-2e7c-4a9d-9f31-c0481de52aa8",
  "OrganizationalUnitRoot": "contoso.onmicrosoft.com"
}

Notes: The {key} is the remote domain Identity (e.g. “Default”), not the DNS domain name.

Related: GET /exchange/v1.0/remoteDomains

Get a single remoteDomains entry - not found

Returns a 404 when the supplied {key} identity does not resolve to an existing remote domain. Backed by Get-RemoteDomain with -Identity {key}.

GET /exchange/v1.0/remoteDomains/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 404 Not Found

{
  "error": {
    "code": "NotFound",
    "message": "Exchange object 'does-not-exist-12345' could not be found.",
    "target": "identity",
    "innerError": {
      "cmdlet": "Get-RemoteDomain"
    }
  },
  "correlationId": "0HNLSU6PPVJ03:00000001"
}

Notes: The {key} is the remote domain Identity; an unrecognized identity surfaces the canonical NotFound error envelope.

Related: GET /exchange/v1.0/remoteDomains

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

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

Backing cmdlet: Set-RemoteDomain. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
allowedOOFType	body
autoForwardEnabled	body
autoReplyEnabled	body
byteEncoderTypeFor7BitCharsets	body
characterSet	body
contentType	body
deliveryReportEnabled	body
displaySenderName	body
isInternal	body
lineWrapSize	body
meetingForwardNotificationEnabled	body
messageCountThreshold	body
name	body
ndrDiagnosticInfoEnabled	body
ndrEnabled	body
nonMimeCharacterSet	body
preferredInternetCodePageForShiftJis	body
requiredCharsetCoverage	body
targetDeliveryDomain	body
tnefEnabled	body
trustedMailInboundEnabled	body
trustedMailOutboundEnabled	body
useSimpleDisplayName	body
dryRun	query	bool (switch)

Update a remote-domain configuration

Partial update via Set-RemoteDomain. Only fields in the SetWritable allowlist are accepted (e.g. AllowedOOFType, AutoReplyEnabled, ContentType). Returns 200 with the re-fetched entity.

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

{
  "allowedOOFType": "InternalLegacy",
  "autoReplyEnabled": false,
  "contentType": "MimeHtmlText"
}

HTTP/1.1 200 OK

{
  "Id": "exonaut-sample-remoteDomains",
  "Identity": "exonaut-sample-remoteDomains",
  "Name": "exonaut-sample-remoteDomains",
  "DomainName": "contoso.com",
  "AllowedOOFType": "InternalLegacy",
  "AutoReplyEnabled": false,
  "ContentType": "MimeHtmlText"
}

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

Related: GET /exchange/v1.0/remoteDomains

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

DELETE /remoteDomains/{key} - removes the remote-domain config. The built-in “Default” entry cannot be removed.

Backing cmdlet: Remove-RemoteDomain. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete a remote-domain configuration

Removes the remote-domain config via Remove-RemoteDomain. The built-in “Default” entry cannot be removed. Returns 204 with no body.

DELETE /exchange/v1.0/remoteDomains/{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/remoteDomains

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