Email - Send

Queues an email message to be sent to one or more recipients

POST {endpoint}/emails:send?api-version=2023-03-31

URI Parameters

Name In Required Type Description
endpoint
path True

string

url

The communication resource, for example https://my-resource.communication.azure.com

api-version
query True

string

Version of API to invoke.

Request Header

Name Required Type Description
Authorization True

string

An authentication string containing a signature generated using HMAC-SHA256 scheme.

Operation-Id

string

uuid

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.

x-ms-client-request-id

string

uuid

Tracking ID sent with the request to help with debugging.

Request Body

Name Required Type Description
content True

EmailContent

Email content to be sent.

recipients True

EmailRecipients

Recipients for the email.

senderAddress True

string

Sender email address from a verified domain.

attachments

EmailAttachment[]

List of attachments. Please note that we limit the total size of an email request (which includes attachments) to 10MB.

headers

object

Custom email headers to be passed.

replyTo

EmailAddress[]

Email addresses where recipients' replies will be sent to.

userEngagementTrackingDisabled

boolean

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.

Responses

Name Type Description
202 Accepted

EmailSendResult

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: string
  • retry-after: integer
Other Status Codes

ErrorResponse

Error

Headers

x-ms-error-code: string

Security

Authorization

An authentication string containing a signature generated using HMAC-SHA256 scheme.

Type: apiKey
In: header

Examples

Send Email

Sample request

POST https://contoso.westus.communications.azure.com/emails:send?api-version=2023-03-31


{
  "headers": {
    "ClientCorrelationId": "123",
    "ClientCustomHeaderName": "ClientCustomHeaderValue"
  },
  "senderAddress": "abc@domain.com",
  "content": {
    "subject": "An exciting offer especially for you!",
    "plainText": "This exciting offer was created especially for you, our most loyal customer.",
    "html": "<html><head><title>Exciting offer!</title></head><body><h1>This exciting offer was created especially for you, our most loyal customer.</h1></body></html>"
  },
  "recipients": {
    "to": [
      {
        "address": "john.doe@domain.com",
        "displayName": "John Doe"
      },
      {
        "address": "jane.doe@domain2.com",
        "displayName": "Jane Doe"
      }
    ],
    "cc": [
      {
        "address": "wendy@someotherdomain.com",
        "displayName": "Wendy"
      },
      {
        "address": "jimmy@anotherdomain.com",
        "displayName": "Jimmy Johns"
      }
    ],
    "bcc": [
      {
        "address": "bob@anotherdomain.com",
        "displayName": "Bob"
      },
      {
        "address": "mail@yetanotherdomain.com",
        "displayName": "Another DisplayName"
      }
    ]
  },
  "attachments": [
    {
      "name": "MyAttachment.pdf",
      "contentType": "application/pdf",
      "contentInBase64": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
    },
    {
      "name": "MyAttachment2.docx",
      "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "contentInBase64": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
    }
  ],
  "replyTo": [
    {
      "address": "contoso-support@contoso.com",
      "displayName": "Contoso Support"
    }
  ],
  "userEngagementTrackingDisabled": true
}

Sample response

Operation-Location: https://contoso.westus.communications.azure.com//emails/operations/8540c0de-899f-5cce-acb5-3ec493af3800?api-version=2023-03-31
retry-after: 20
{
  "id": "8540c0de-899f-5cce-acb5-3ec493af3800",
  "status": "Running"
}

Definitions

Name Description
EmailAddress

An object representing the email address and its display name

EmailAttachment

Attachment to the email.

EmailContent

Content of the email.

EmailMessage

Message payload for sending an email

EmailRecipients

Recipients of the email

EmailSendResult

Status of the long running operation

EmailSendStatus

Status of operation.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

EmailAddress

An object representing the email address and its display name

Name Type Description
address

string

Email address.

displayName

string

Email display name.

EmailAttachment

Attachment to the email.

Name Type Description
contentInBase64

string

Base64 encoded contents of the attachment

contentType

string

MIME type of the content being attached.

name

string

Name of the attachment

EmailContent

Content of the email.

Name Type Description
html

string

Html version of the email message.

plainText

string

Plain text version of the email message.

subject

string

Subject of the email message

EmailMessage

Message payload for sending an email

Name Type Description
attachments

EmailAttachment[]

List of attachments. Please note that we limit the total size of an email request (which includes attachments) to 10MB.

content

EmailContent

Email content to be sent.

headers

object

Custom email headers to be passed.

recipients

EmailRecipients

Recipients for the email.

replyTo

EmailAddress[]

Email addresses where recipients' replies will be sent to.

senderAddress

string

Sender email address from a verified domain.

userEngagementTrackingDisabled

boolean

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.

EmailRecipients

Recipients of the email

Name Type Description
bcc

EmailAddress[]

Email BCC recipients

cc

EmailAddress[]

Email CC recipients

to

EmailAddress[]

Email To recipients

EmailSendResult

Status of the long running operation

Name Type Description
error

ErrorDetail

Error details when status is a non-success terminal state.

id

string

The unique id of the operation. Use a UUID.

status

EmailSendStatus

Status of operation.

EmailSendStatus

Status of operation.

Name Type Description
Canceled

string

Failed

string

NotStarted

string

Running

string

Succeeded

string

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.