{ "swagger": "2.0", "info": { "title": "Azure Communication Services Management API", "version": "2025-05-01", "description": "REST API for Email Services/Domains" }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "host": "management.azure.com", "schemes": [ "https" ], "securityDefinitions": { "azure_auth": { "type": "oauth2", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "flow": "implicit", "description": "Azure Active Directory OAuth2 Flow", "scopes": { "user_impersonation": "impersonate your user account" } } }, "paths": { "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/emailServices/{emailServiceName}/domains/{domainName}": { "get": { "description": "Get the Domains resource and its properties.", "operationId": "Domains_Get", "summary": "Get", "tags": [ "Domains" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "EmailServices.json#/parameters/EmailServiceName" }, { "$ref": "#/parameters/DomainName" } ], "responses": { "200": { "description": "Success. The response describe the corresponding Domains resource.", "schema": { "$ref": "#/definitions/DomainResource" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Get Domains resource": { "$ref": "./examples/domains/get.json" } } }, "put": { "description": "Add a new Domains resource under the parent EmailService resource or update an existing Domains resource.", "operationId": "Domains_CreateOrUpdate", "summary": "Create Or Update", "tags": [ "Domains" ], "parameters": [ { "name": "parameters", "in": "body", "description": "Parameters for the create or update operation", "required": true, "schema": { "$ref": "#/definitions/DomainResource" } }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "EmailServices.json#/parameters/EmailServiceName" }, { "$ref": "#/parameters/DomainName" } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "The create or update request was completed successfully", "schema": { "$ref": "#/definitions/DomainResource" } }, "201": { "description": "The create or update request was accepted", "headers": { "Azure-AsyncOperation": { "description": "URL to query for status of the operation.", "type": "string" } }, "schema": { "$ref": "#/definitions/DomainResource" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "azure-async-operation" }, "x-ms-examples": { "Create or update Domains resource": { "$ref": "./examples/domains/createOrUpdate.json" } } }, "delete": { "description": "Operation to delete a Domains resource.", "operationId": "Domains_Delete", "summary": "Delete", "tags": [ "Domains" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "EmailServices.json#/parameters/EmailServiceName" }, { "$ref": "#/parameters/DomainName" } ], "responses": { "200": { "description": "The delete operation was successful." }, "202": { "description": "The delete operation is being performed in the background.", "headers": { "location": { "description": "URL to query for status of the operation.", "type": "string" } } }, "204": { "description": "The resource did not exist." }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "x-ms-examples": { "Delete Domains resource": { "$ref": "./examples/domains/delete.json" } } }, "patch": { "description": "Operation to update an existing Domains resource.", "operationId": "Domains_Update", "summary": "Update", "tags": [ "Domains" ], "parameters": [ { "name": "parameters", "in": "body", "description": "Parameters for the update operation", "required": true, "schema": { "$ref": "#/definitions/UpdateDomainRequestParameters" } }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "EmailServices.json#/parameters/EmailServiceName" }, { "$ref": "#/parameters/DomainName" } ], "responses": { "200": { "description": "The update request was successful", "schema": { "$ref": "#/definitions/DomainResource" } }, "201": { "description": "The update request was accepted", "headers": { "Azure-AsyncOperation": { "description": "URL to query for status of the operation.", "type": "string" } }, "schema": { "$ref": "#/definitions/DomainResource" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "azure-async-operation" }, "x-ms-examples": { "Update Domains resource": { "$ref": "./examples/domains/update.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/emailServices/{emailServiceName}/domains": { "get": { "description": "Handles requests to list all Domains resources under the parent EmailServices resource.", "operationId": "Domains_ListByEmailServiceResource", "summary": "List by EmailService", "tags": [ "Domains" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "EmailServices.json#/parameters/EmailServiceName" } ], "responses": { "200": { "description": "Success. The response describes the list of Domains resources under the parent EmailServices resource.", "schema": { "$ref": "#/definitions/DomainResourceList" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-pageable": { "nextLinkName": "nextLink" }, "x-ms-examples": { "List Domains resources by EmailServiceName": { "$ref": "./examples/domains/listByEmailService.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/emailServices/{emailServiceName}/domains/{domainName}/initiateVerification": { "post": { "description": "Initiate verification of DNS record.", "operationId": "Domains_InitiateVerification", "summary": "Initiate Verification", "tags": [ "Domains" ], "parameters": [ { "name": "parameters", "in": "body", "schema": { "$ref": "#/definitions/VerificationParameter" }, "description": "Type of verification to be initiated.", "required": true }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "EmailServices.json#/parameters/EmailServiceName" }, { "$ref": "#/parameters/DomainName" } ], "responses": { "202": { "description": "The initiateVerification operation is being performed in the background.", "headers": { "location": { "description": "URL to query for status of the operation.", "type": "string" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "produces": [ "application/json" ], "x-ms-examples": { "Initiate verification": { "$ref": "./examples/domains/initiateVerification.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/emailServices/{emailServiceName}/domains/{domainName}/cancelVerification": { "post": { "description": "Cancel verification of DNS record.", "operationId": "Domains_CancelVerification", "summary": "Cancel Verification", "tags": [ "Domains" ], "parameters": [ { "name": "parameters", "in": "body", "schema": { "$ref": "#/definitions/VerificationParameter" }, "description": "Type of verification to be canceled.", "required": true }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "EmailServices.json#/parameters/EmailServiceName" }, { "$ref": "#/parameters/DomainName" } ], "responses": { "202": { "description": "The cancelVerification operation is being performed in the background.", "headers": { "location": { "description": "URL to query for status of the operation.", "type": "string" } } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "produces": [ "application/json" ], "x-ms-examples": { "Cancel verification": { "$ref": "./examples/domains/cancelVerification.json" } } } } }, "definitions": { "VerificationParameter": { "description": "Input parameter for verification APIs", "type": "object", "required": [ "verificationType" ], "properties": { "verificationType": { "description": "Type of verification.", "enum": [ "Domain", "SPF", "DKIM", "DKIM2", "DMARC" ], "type": "string", "x-ms-enum": { "name": "VerificationType", "modelAsString": true } } } }, "VerificationStatusRecord": { "description": "A class that represents a VerificationStatus record.", "type": "object", "properties": { "status": { "description": "Status of the verification operation.", "enum": [ "NotStarted", "VerificationRequested", "VerificationInProgress", "VerificationFailed", "Verified", "CancellationRequested" ], "type": "string", "readOnly": true, "x-ms-enum": { "name": "VerificationStatus", "modelAsString": true } }, "errorCode": { "description": "Error code. This property will only be present if the status is UnableToVerify.", "type": "string", "readOnly": true } } }, "DnsRecord": { "description": "A class that represents a VerificationStatus record.", "type": "object", "properties": { "type": { "description": "Type of the DNS record. Example: TXT", "type": "string", "readOnly": true }, "name": { "description": "Name of the DNS record.", "type": "string", "readOnly": true }, "value": { "description": "Value of the DNS record.", "type": "string", "readOnly": true }, "ttl": { "description": "Represents an expiry time in seconds to represent how long this entry can be cached by the resolver, default = 3600sec.", "type": "integer", "format": "int32", "readOnly": true } } }, "DomainProperties": { "description": "A class that describes the properties of a Domains resource.", "type": "object", "required": [ "domainManagement" ], "properties": { "provisioningState": { "description": "Provisioning state of the resource.", "enum": [ "Unknown", "Succeeded", "Failed", "Canceled", "Running", "Creating", "Updating", "Deleting", "Moving" ], "type": "string", "readOnly": true, "x-ms-enum": { "name": "Domains_ProvisioningState", "modelAsString": true } }, "dataLocation": { "description": "The location where the Domains resource data is stored at rest.", "type": "string", "readOnly": true }, "fromSenderDomain": { "description": "P2 sender domain that is displayed to the email recipients [RFC 5322].", "type": "string", "readOnly": true }, "mailFromSenderDomain": { "description": "P1 sender domain that is present on the email envelope [RFC 5321].", "type": "string", "readOnly": true }, "domainManagement": { "$ref": "#/definitions/DomainManagement" }, "verificationStates": { "description": "List of VerificationStatusRecord", "type": "object", "properties": { "Domain": { "$ref": "#/definitions/VerificationStatusRecord" }, "SPF": { "$ref": "#/definitions/VerificationStatusRecord" }, "DKIM": { "$ref": "#/definitions/VerificationStatusRecord" }, "DKIM2": { "$ref": "#/definitions/VerificationStatusRecord" }, "DMARC": { "$ref": "#/definitions/VerificationStatusRecord" } }, "readOnly": true }, "verificationRecords": { "description": "List of DnsRecord", "type": "object", "properties": { "Domain": { "$ref": "#/definitions/DnsRecord" }, "SPF": { "$ref": "#/definitions/DnsRecord" }, "DKIM": { "$ref": "#/definitions/DnsRecord" }, "DKIM2": { "$ref": "#/definitions/DnsRecord" }, "DMARC": { "$ref": "#/definitions/DnsRecord" } }, "readOnly": true }, "userEngagementTracking": { "$ref": "#/definitions/UserEngagementTracking" } } }, "DomainManagement": { "description": "Describes how a Domains resource is being managed.", "enum": [ "AzureManaged", "CustomerManaged", "CustomerManagedInExchangeOnline" ], "type": "string", "x-ms-enum": { "name": "DomainManagement", "modelAsString": true } }, "UserEngagementTracking": { "description": "Describes whether user engagement tracking is enabled or disabled.", "enum": [ "Disabled", "Enabled" ], "type": "string", "x-ms-enum": { "name": "UserEngagementTracking", "modelAsString": true } }, "DomainResource": { "description": "A class representing a Domains resource.", "type": "object", "allOf": [ { "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/TrackedResource" } ], "properties": { "properties": { "$ref": "#/definitions/DomainProperties", "description": "The properties of a Domains resource.", "x-ms-client-flatten": true } } }, "UpdateDomainProperties": { "description": "A class that describes the updatable properties of a Domains resource.", "type": "object", "properties": { "userEngagementTracking": { "$ref": "#/definitions/UserEngagementTracking" } } }, "UpdateDomainRequestParameters": { "description": "A class that describes the PATCH request parameters of a Domains resource.", "type": "object", "allOf": [ { "$ref": "CommunicationServices.json#/definitions/TaggedResource" } ], "properties": { "properties": { "$ref": "#/definitions/UpdateDomainProperties", "x-ms-client-flatten": true } } }, "DomainResourceList": { "description": "Object that includes an array of Domains resource and a possible link for next set.", "type": "object", "properties": { "value": { "description": "List of Domains resource", "type": "array", "items": { "$ref": "#/definitions/DomainResource" } }, "nextLink": { "description": "The URL the client should use to fetch the next page (per server side paging).\r\nIt's null for now, added for future use.", "type": "string" } } } }, "parameters": { "DomainName": { "name": "domainName", "in": "path", "description": "The name of the Domains resource.", "minLength": 1, "maxLength": 253, "required": true, "type": "string", "x-ms-parameter-location": "method" } } }