From ac29c822ecd5f6054cd17c46839e7c04a1114c6d Mon Sep 17 00:00:00 2001 From: apattath Date: Tue, 14 Mar 2023 17:45:00 -0700 Subject: [PATCH] Azure Communication Services Email API for GA (#22979) * Copy existing preview version of CommunicationServicesEmail API to stable folder in preparation for GA * update version to 2023-03-31 * update comment about events for 202 result * update readme file * updated description of Operation-ID header --- .../communication/data-plane/Email/readme.md | 13 +- .../CommunicationServicesEmail.json | 384 ++++++++++++++++++ ...tionStatusReturnsFailedTerminalStatus.json | 20 + ...erationStatusReturnsNonTerminalStatus.json | 19 + ...ionStatusReturnsSuccessTerminalStatus.json | 16 + .../stable/2023-03-31/examples/SendEmail.json | 84 ++++ 6 files changed, 535 insertions(+), 1 deletion(-) create mode 100644 specification/communication/data-plane/Email/stable/2023-03-31/CommunicationServicesEmail.json create mode 100644 specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsFailedTerminalStatus.json create mode 100644 specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsNonTerminalStatus.json create mode 100644 specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsSuccessTerminalStatus.json create mode 100644 specification/communication/data-plane/Email/stable/2023-03-31/examples/SendEmail.json diff --git a/specification/communication/data-plane/Email/readme.md b/specification/communication/data-plane/Email/readme.md index 5006341e8452..8de39c6fcec6 100644 --- a/specification/communication/data-plane/Email/readme.md +++ b/specification/communication/data-plane/Email/readme.md @@ -26,7 +26,7 @@ These are the global settings for the communicationservices. ```yaml openapi-type: data-plane -tag: package-2023-01-15-preview +tag: package-2023-03-31 ``` ### Tag: package-2021-10-01-preview @@ -51,6 +51,17 @@ title: Azure Communication Services ``` +### Tag: package-2023-03-31 + +These settings apply only when `--tag=package-2023-03-31` is specified on the command line. + +```yaml $(tag) == 'package-2023-03-31' +input-file: + - stable/2023-03-31/CommunicationServicesEmail.json +title: + Azure Communication Services +``` + --- # Code Generation diff --git a/specification/communication/data-plane/Email/stable/2023-03-31/CommunicationServicesEmail.json b/specification/communication/data-plane/Email/stable/2023-03-31/CommunicationServicesEmail.json new file mode 100644 index 000000000000..c68af040e699 --- /dev/null +++ b/specification/communication/data-plane/Email/stable/2023-03-31/CommunicationServicesEmail.json @@ -0,0 +1,384 @@ +{ + "swagger": "2.0", + "info": { + "title": "EmailClient", + "description": "Azure Communication Email Service", + "version": "2023-03-31" + }, + "paths": { + "/emails/operations/{operationId}": { + "get": { + "tags": [ + "EmailGetSendResult" + ], + "summary": "Gets the status of the email send operation.", + "operationId": "Email_GetSendResult", + "produces": [ + "application/json" + ], + "parameters": [ + { + "in": "path", + "name": "operationId", + "description": "ID of the long running operation (GUID) returned from a previous call to send email", + "required": true, + "type": "string" + }, + { + "$ref": "#/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.", + "type": "string" + } + }, + "schema": { + "$ref": "../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorResponse" + } + }, + "200": { + "description": "Message status was successfully retrieved.", + "headers": { + "retry-after": { + "description": "This header will only be present when the status is a non-terminal status. It indicates the minimum amount of time in seconds to wait before polling for operation status again.", + "type": "integer", + "format": "int32" + } + }, + "schema": { + "$ref": "#/definitions/EmailSendResult" + } + } + }, + "x-ms-examples": { + "Get Message Status FailedTerminalStatus": { + "$ref": "./examples/GetOperationStatusReturnsFailedTerminalStatus.json" + }, + "Get Message Status NonTerminalStatus": { + "$ref": "./examples/GetOperationStatusReturnsNonTerminalStatus.json" + }, + "Get Message Status SuccessTerminalStatus": { + "$ref": "./examples/GetOperationStatusReturnsSuccessTerminalStatus.json" + } + } + } + }, + "/emails:send": { + "post": { + "tags": [ + "EmailSend" + ], + "summary": "Queues an email message to be sent to one or more recipients", + "operationId": "Email_Send", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "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.", + "type": "string", + "required": false, + "format": "uuid" + }, + { + "in": "header", + "name": "x-ms-client-request-id", + "description": "Tracking ID sent with the request to help with debugging.", + "type": "string", + "required": false, + "format": "uuid", + "x-ms-client-name": "ClientRequestId" + }, + { + "$ref": "#/parameters/ApiVersionParameter" + }, + { + "in": "body", + "name": "emailMessage", + "description": "Message payload for sending an email", + "required": true, + "x-ms-client-name": "message", + "schema": { + "$ref": "#/definitions/EmailMessage" + } + } + ], + "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.", + "type": "string" + } + }, + "schema": { + "$ref": "../../../../../common-types/data-plane/v1/types.json#/definitions/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.", + "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.", + "type": "integer", + "format": "int32" + } + }, + "schema": { + "$ref": "#/definitions/EmailSendResult" + } + } + }, + "x-ms-long-running-operation": true, + "x-ms-long-running-operation-options": { + "final-state-via": "azure-async-operation" + }, + "x-ms-examples": { + "Send Email": { + "$ref": "./examples/SendEmail.json" + } + } + } + } + }, + "definitions": { + "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": "../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorDetail" + } + } + }, + "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": "#/definitions/EmailContent" + }, + "recipients": { + "description": "Recipients for the email.", + "$ref": "#/definitions/EmailRecipients" + }, + "attachments": { + "description": "List of attachments. Please note that we limit the total size of an email request (which includes attachments) to 10MB.", + "type": "array", + "items": { + "$ref": "#/definitions/EmailAttachment" + } + }, + "replyTo": { + "description": "Email addresses where recipients' replies will be sent to.", + "type": "array", + "items": { + "$ref": "#/definitions/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" + } + } + }, + "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" + } + } + }, + "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": "Exciting offer!

This exciting offer was created especially for you, our most loyal customer.

" + } + } + }, + "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", + "example": "TWFueSBoYW5kcyBtYWtlIGxpZ2h0I" + } + } + }, + "EmailRecipients": { + "description": "Recipients of the email", + "type": "object", + "required": [ + "to" + ], + "properties": { + "to": { + "description": "Email To recipients", + "type": "array", + "items": { + "$ref": "#/definitions/EmailAddress" + } + }, + "cc": { + "description": "Email CC recipients", + "type": "array", + "x-ms-client-name": "CC", + "items": { + "$ref": "#/definitions/EmailAddress" + } + }, + "bcc": { + "description": "Email BCC recipients", + "type": "array", + "x-ms-client-name": "BCC", + "items": { + "$ref": "#/definitions/EmailAddress" + } + } + } + } + }, + "parameters": { + "ApiVersionParameter": { + "in": "query", + "name": "api-version", + "description": "Version of API to invoke.", + "required": true, + "type": "string", + "x-ms-parameter-location": "client" + } + }, + "securityDefinitions": { + "Authorization": { + "type": "apiKey", + "name": "Authorization", + "in": "header", + "description": "An authentication string containing a signature generated using HMAC-SHA256 scheme." + } + }, + "security": [ + { + "Authorization": [] + } + ], + "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" + } + ] + } +} diff --git a/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsFailedTerminalStatus.json b/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsFailedTerminalStatus.json new file mode 100644 index 000000000000..554ae3efa7b9 --- /dev/null +++ b/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsFailedTerminalStatus.json @@ -0,0 +1,20 @@ +{ + "parameters": { + "endpoint": "https://contoso.westus.communications.azure.com", + "api-version": "2023-03-31", + "authorization": "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=aaaa", + "operationId": "F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4" + }, + "responses": { + "200": { + "body": { + "id": "F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4", + "status": "Failed", + "error": { + "code": "EmailDropped", + "message": "Email was dropped after several attempts to deliver." + } + } + } + } +} diff --git a/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsNonTerminalStatus.json b/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsNonTerminalStatus.json new file mode 100644 index 000000000000..294c5ff9ac61 --- /dev/null +++ b/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsNonTerminalStatus.json @@ -0,0 +1,19 @@ +{ + "parameters": { + "endpoint": "https://contoso.westus.communications.azure.com", + "api-version": "2023-03-31", + "authorization": "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=aaaa", + "operationId": "F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4" + }, + "responses": { + "200": { + "headers": { + "retry-after": 100 + }, + "body": { + "id": "F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4", + "status": "Running" + } + } + } +} diff --git a/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsSuccessTerminalStatus.json b/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsSuccessTerminalStatus.json new file mode 100644 index 000000000000..27b192cd3a2a --- /dev/null +++ b/specification/communication/data-plane/Email/stable/2023-03-31/examples/GetOperationStatusReturnsSuccessTerminalStatus.json @@ -0,0 +1,16 @@ +{ + "parameters": { + "endpoint": "https://contoso.westus.communications.azure.com", + "api-version": "2023-03-31", + "authorization": "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=aaaa", + "operationId": "F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4" + }, + "responses": { + "200": { + "body": { + "id": "F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4", + "status": "Succeeded" + } + } + } +} diff --git a/specification/communication/data-plane/Email/stable/2023-03-31/examples/SendEmail.json b/specification/communication/data-plane/Email/stable/2023-03-31/examples/SendEmail.json new file mode 100644 index 000000000000..dbd279376213 --- /dev/null +++ b/specification/communication/data-plane/Email/stable/2023-03-31/examples/SendEmail.json @@ -0,0 +1,84 @@ +{ + "parameters": { + "endpoint": "https://contoso.westus.communications.azure.com", + "api-version": "2023-03-31", + "x-ms-client-request-id": "1377af77-47e8-4fb3-8e84-5a848305daea", + "operation-id": "8540c0de-899f-5cce-acb5-3ec493af3800", + "authorization": "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=aaaa", + "emailMessage": { + "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": "Exciting offer!

This exciting offer was created especially for you, our most loyal customer.

" + }, + "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": "TWFueSBoYW5kcyBtYWtlIGxpZ2h0IHdvcmsu" + }, + { + "name": "MyAttachment2.docx", + "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", + "contentInBase64": "pZ2h0IHdvcmsu5kcyBtYWtlIGxpZ2h0IHdvcmsu" + } + ], + "replyTo": [ + { + "address": "contoso-support@contoso.com", + "displayName": "Contoso Support" + } + ], + "userEngagementTrackingDisabled": true + } + }, + "responses": { + "202": { + "headers": { + "Operation-Location": "https://contoso.westus.communications.azure.com//emails/operations/8540c0de-899f-5cce-acb5-3ec493af3800?api-version=2023-03-31", + "retry-after": 20 + }, + "body": { + "id": "8540c0de-899f-5cce-acb5-3ec493af3800", + "status": "Running" + } + } + } +}