Email - Send

Reference

Service:: Communication

API Version:: 2023-03-31

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

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

HTTP

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

Status code:: 202

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

Response Body

{
  "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.

Email - Send

URI Parameters

Request Header

Request Body

Responses

Security

Authorization

Examples

Send Email

Sample Request

Sample Response

Definitions

EmailAddress

EmailAttachment

EmailContent

EmailMessage

EmailRecipients

EmailSendResult

EmailSendStatus

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

Additional resources