CommunicationServicesEmail.json

{
  "swagger": "2.0",
  "info": {
    "title": "CommunicationEmailClient",
    "description": "Azure Communication Email Service",
    "version": "2021-10-01-preview"
  },
  "paths": {
    "/emails/{messageId}/status": {
      "get": {
        "tags": [
          "EmailGetSendStatus"
        ],
        "summary": "Gets the status of a message sent previously.",
        "operationId": "Email_GetSendStatus",
        "produces": [
          "application/json"
        ],
        "consumes": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "messageId",
            "description": "System generated message id (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/stable/2021-03-07/common.json#/definitions/CommunicationErrorResponse"
            }
          },
          "200": {
            "description": "Message status was successfully retrieved.",
            "headers": {
              "Retry-After": {
                "description": "Amount of time client should wait before retrying the request, specified in seconds ",
                "type": "integer"
              }
            },
            "schema": {
              "$ref": "#/definitions/SendStatusResult"
            }
          }
        },
        "x-ms-examples": {
          "Get Message Status": {
            "$ref": "./examples/GetSendStatus.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": "repeatability-request-id",
            "description": "If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated, globally unique for all time, identifier for the request. It is recommended to use version 4 (random) UUIDs.",
            "type": "string",
            "required": true
          },
          {
            "in": "header",
            "name": "repeatability-first-sent",
            "description": "Must be sent by clients to specify that a request is repeatable. Repeatability-First-Sent is used to specify the date and time at which the request was first created in the IMF-fix date form of HTTP-date as defined in RFC7231. eg- Tue, 26 Mar 2019 16:06:51 GMT",
            "type": "string",
            "required": true
          },
          {
            "$ref": "#/parameters/ApiVersionParameter"
          },
          {
            "in": "body",
            "name": "emailMessage",
            "description": "Message payload for sending an email",
            "required": true,
            "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/stable/2021-03-07/common.json#/definitions/CommunicationErrorResponse"
            }
          },
          "202": {
            "description": "Message accepted, the `Operation-Location` header contains the URL to poll for the message status.",
            "headers": {
              "Repeatability-Result": {
                "description": "Status of a repeatable request.",
                "type": "string"
              },
              "Operation-Location": {
                "description": "Location url of where to poll the status of this message from.",
                "type": "string"
              },
              "Retry-After": {
                "description": "Amount of time client should wait before retrying the request, specified in seconds ",
                "type": "integer"
              },
              "x-ms-request-id": {
                "description": "System generated GUID indicating the id of this specific message, to be used for tracking purposes.",
                "type": "string"
              }
            }
          }
        },
        "x-ms-examples": {
          "Send Email": {
            "$ref": "./examples/SendEmail.json"
          }
        }
      }
    }
  },
  "definitions": {
    "EmailMessage": {
      "description": "Message payload for sending an email",
      "required": [
        "sender",
        "content",
        "recipients"
      ],
      "type": "object",
      "properties": {
        "headers": {
          "description": "Custom email headers to be passed.",
          "type": "array",
          "x-ms-client-name": "CustomHeaders",
          "items": {
            "$ref": "#/definitions/EmailCustomHeader"
          }
        },
        "sender": {
          "description": "Sender email address from a verified domain.",
          "type": "string",
          "example": "info@contoso.com"
        },
        "content": {
          "description": "Email content to be sent.",
          "$ref": "#/definitions/EmailContent"
        },
        "importance": {
          "description": "The importance type for the email.",
          "$ref": "#/definitions/EmailImportance"
        },
        "recipients": {
          "description": "Recipients for the email.",
          "$ref": "#/definitions/EmailRecipients"
        },
        "attachments": {
          "description": "list of attachments",
          "type": "array",
          "items": {
            "$ref": "#/definitions/EmailAttachment"
          }
        },
        "replyTo": {
          "description": "Email addresses where recipients' replies will be sent to.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/EmailAddress"
          }
        },
        "disableUserEngagementTracking": {
          "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"
        }
      }
    },
    "EmailCustomHeader": {
      "description": "Custom header for email.",
      "type": "object",
      "required": [
        "name",
        "value"
      ],
      "properties": {
        "name": {
          "description": "Header name.",
          "type": "string",
          "example": ""
        },
        "value": {
          "description": "Header value.",
          "type": "string",
          "example": ""
        }
      }
    },
    "EmailAddress": {
      "description": "An object representing the email address and its display name",
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "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": "<html><head><title>Exciting offer!</title></head><body><h1>This exciting offer was created especially for you, our most loyal customer.</h1></body></html>"
        }
      }
    },
    "EmailImportance": {
      "description": "The importance type for the email.",
      "enum": [
        "high",
        "normal",
        "low"
      ],
      "type": "string",
      "default": "normal",
      "x-ms-enum": {
        "name": "EmailImportance",
        "modelAsString": true
      }
    },
    "EmailAttachment": {
      "description": "Attachment to the email.",
      "type": "object",
      "required": [
        "name",
        "attachmentType",
        "contentBytesBase64"
      ],
      "properties": {
        "name": {
          "description": "Name of the attachment",
          "type": "string",
          "example": "attachment.pdf"
        },
        "attachmentType": {
          "$ref": "#/definitions/EmailAttachmentType"
        },
        "contentBytesBase64": {
          "description": "Base64 encoded contents of the attachment",
          "type": "string",
          "example": "TWFueSBoYW5kcyBtYWtlIGxpZ2h0I"
        }
      }
    },
    "EmailAttachmentType": {
      "description": "The type of attachment file.",
      "enum": [
        "avi",
        "bmp",
        "doc",
        "docm",
        "docx",
        "gif",
        "jpeg",
        "mp3",
        "one",
        "pdf",
        "png",
        "ppsm",
        "ppsx",
        "ppt",
        "pptm",
        "pptx",
        "pub",
        "rpmsg",
        "rtf",
        "tif",
        "txt",
        "vsd",
        "wav",
        "wma",
        "xls",
        "xlsb",
        "xlsm",
        "xlsx"
      ],
      "type": "string",
      "x-ms-enum": {
        "name": "EmailAttachmentType",
        "modelAsString": true
      }
    },
    "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",
          "items": {
            "$ref": "#/definitions/EmailAddress"
          }
        },
        "bCC": {
          "description": "Email BCC recipients",
          "type": "array",
          "items": {
            "$ref": "#/definitions/EmailAddress"
          }
        }
      }
    },
    "SendStatusResult": {
      "description": "Status of an email message that was sent previously.",
      "type": "object",
      "required": [
        "messageId",
        "status"
      ],
      "properties": {
        "messageId": {
          "description": "System generated id of an email message sent.",
          "type": "string",
          "example": "F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4"
        },
        "status": {
          "$ref": "#/definitions/SendStatus"
        }
      }
    },
    "SendStatus": {
      "description": "The type indicating the status of a request.",
      "enum": [
        "queued",
        "outForDelivery",
        "dropped"
      ],
      "type": "string",
      "x-ms-enum": {
        "name": "SendStatus",
        "modelAsString": true,
        "values": [
          {
            "value": "queued",
            "description": "The message has passed basic validations and has been queued to be processed further."
          },
          {
            "value": "outForDelivery",
            "description": "The message has been processed and is now out for delivery."
          },
          {
            "value": "dropped",
            "description": "The message could not be processed and was dropped."
          }
        ]
      }
    }
  },
  "parameters": {
    "ApiVersionParameter": {
      "in": "query",
      "name": "api-version",
      "description": "Version of API to invoke.",
      "required": true,
      "enum": [
        "2021-10-01-preview"
      ],
      "type": "string"
    }
  },
  "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",
        "in": "path",
        "x-ms-skip-url-encoding": true,
        "x-ms-parameter-location": "client"
      }
    ]
  }
}