Microsoft Azure Communication Services Email Send API

openapi: 3.2.0
info:
  title: EmailClient Email Send API
  description: Azure Communication Email Service
  version: '2025-09-01'
security:
- Authorization: []
tags:
- name: EmailSend
paths:
  /emails:send:
    post:
      tags:
      - EmailSend
      summary: Queues an email message to be sent to one or more recipients
      operationId: Email_Send
      parameters:
      - in: header
        name: Operation-Id
        description: This is the ID provided by the customer to identify the long running operation. If an ID is not provided by the customer, the service will generate one.
        required: false
        schema:
          type: string
          format: uuid
      - in: header
        name: x-ms-client-request-id
        description: Tracking ID sent with the request to help with debugging.
        required: false
        x-ms-client-name: ClientRequestId
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        default:
          description: Error
          headers:
            x-ms-error-code:
              description: Error code - this will be the same as the code in the error property in the response body.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '202':
          description: 'The service has accepted the request and will start processing the message later. It will return ''Accepted'' immediately and include an ''Operation-Location'' header. Client side should further query the operation/message status using the URL specified in ''Operation-Location'' header. Once the send operation has succeeded, you can get additional status about email delivery through either Azure Monitor or Event Grid events (for events reference, please refer to: https://learn.microsoft.com/en-us/azure/event-grid/communication-services-email-events)'
          headers:
            Operation-Location:
              description: Location url of where to poll the status of this operation from.
              schema:
                type: string
            retry-after:
              description: This header will only be present when the operation status is a non-terminal status. It indicates the minimum amount of time in seconds to wait before polling for operation status again.
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailSendResult'
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: azure-async-operation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailMessage'
        description: Message payload for sending an email
        required: true
components:
  schemas:
    EmailContent:
      description: Content of the email.
      type: object
      required:
      - subject
      properties:
        subject:
          description: Subject of the email message
          type: string
          example: An exciting offer especially for you!
        plainText:
          description: Plain text version of the email message.
          type: string
          example: This exciting offer was created especially for you, our most loyal customer.
        html:
          description: Html version of the email message.
          type: string
          example: <html><head><title>Exciting offer!</title></head><body><h1>This exciting offer was created especially for you, our most loyal customer.</h1></body></html>
    ErrorDetail:
      type: object
      description: The error detail.
      properties:
        code:
          readOnly: true
          type: string
          description: The error code.
        message:
          readOnly: true
          type: string
          description: The error message.
        target:
          readOnly: true
          type: string
          description: The error target.
        details:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          x-ms-identifiers: []
          description: The error details.
        additionalInfo:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/ErrorAdditionalInfo'
          x-ms-identifiers: []
          description: The error additional info.
    EmailSendResult:
      description: Status of the long running operation
      required:
      - id
      - status
      type: object
      properties:
        id:
          description: The unique id of the operation. Use a UUID.
          type: string
          example: 8540c0de-899f-5cce-acb5-3ec493af3800
        status:
          description: Status of operation.
          enum:
          - NotStarted
          - Running
          - Succeeded
          - Failed
          - Canceled
          type: string
          x-ms-enum:
            name: EmailSendStatus
            modelAsString: true
        error:
          description: Error details when status is a non-success terminal state.
          $ref: '#/components/schemas/ErrorDetail'
    EmailAddress:
      description: An object representing the email address and its display name
      type: object
      required:
      - address
      properties:
        address:
          description: Email address.
          type: string
          example: abc@contoso.com
        displayName:
          description: Email display name.
          type: string
          example: abc
    EmailMessage:
      description: Message payload for sending an email
      required:
      - senderAddress
      - content
      - recipients
      type: object
      properties:
        headers:
          description: Custom email headers to be passed.
          type: object
          additionalProperties:
            type: string
        senderAddress:
          description: Sender email address from a verified domain.
          type: string
          example: info@contoso.com
        content:
          description: Email content to be sent.
          $ref: '#/components/schemas/EmailContent'
        recipients:
          description: Recipients for the email.
          $ref: '#/components/schemas/EmailRecipients'
        attachments:
          description: List of attachments. Please note that we limit the total size of an email request (which includes both regular and inline attachments) to 10MB.
          type: array
          items:
            $ref: '#/components/schemas/EmailAttachment'
        replyTo:
          description: Email addresses where recipients' replies will be sent to.
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        userEngagementTrackingDisabled:
          description: Indicates whether user engagement tracking should be disabled for this request if the resource-level user engagement tracking setting was already enabled in the control plane.
          type: boolean
    ErrorResponse:
      type: object
      title: Error response
      description: Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
      properties:
        error:
          description: The error object.
          $ref: '#/components/schemas/ErrorDetail'
    EmailRecipients:
      description: Recipients of the email
      type: object
      required:
      - to
      properties:
        to:
          description: Email To recipients
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
        cc:
          description: Email CC recipients
          type: array
          x-ms-client-name: CC
          items:
            $ref: '#/components/schemas/EmailAddress'
        bcc:
          description: Email BCC recipients
          type: array
          x-ms-client-name: BCC
          items:
            $ref: '#/components/schemas/EmailAddress'
    EmailAttachment:
      description: Attachment to the email.
      type: object
      required:
      - name
      - contentType
      - contentInBase64
      properties:
        name:
          description: Name of the attachment
          type: string
          example: attachment.pdf
        contentType:
          description: MIME type of the content being attached.
          type: string
          example: text/plain
        contentInBase64:
          description: Base64 encoded contents of the attachment
          type: string
          format: byte
          example: TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ=
        contentId:
          description: Unique identifier (CID) to reference an inline attachment.
          type: string
          example: inline_image_id
  parameters:
    ApiVersionParameter:
      in: query
      name: api-version
      description: Version of API to invoke.
      required: true
      x-ms-parameter-location: client
      schema:
        type: string
  securitySchemes:
    Authorization:
      type: apiKey
      name: Authorization
      in: header
      description: An authentication string containing a signature generated using HMAC-SHA256 scheme.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    description: The communication resource, for example https://my-resource.communication.azure.com
    required: true
    type: string
    format: url
    in: path
    x-ms-skip-url-encoding: true
    x-ms-parameter-location: client