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": "