openapi: 3.0.0
info:
  title: Auth0 Authentication actions emails API
  description: Auth0 Authentication API. Endpoints for authentication and authorization using OpenID Connect, OAuth 2.0, SAML, WS-Federation, and Passwordless flows.
  version: 1.0.0
servers:
- url: '{auth0_domain}'
  description: The Authentication API is served over HTTPS.
  variables:
    auth0_domain:
      description: Auth0 domain
      default: https://demo.us.auth0.com
tags:
- name: emails
paths:
  /emails/provider:
    get:
      summary: Get Email Provider
      description: 'Retrieve details of the <a href="https://auth0.com/docs/customize/email/smtp-email-providers">email provider configuration</a> in your tenant. A list of fields to include or exclude may also be specified.

        '
      tags:
      - emails
      parameters:
      - name: fields
        in: query
        description: Comma-separated list of fields to include or exclude (dependent upon include_fields) from the result. Leave empty to retrieve `name` and `enabled`. Additional fields available include `credentials`, `default_from_address`, and `settings`.
        schema:
          type: string
          pattern: ^((name)|(enabled)|(credentials)|(settings)|(default_from_address))(,((name)|(enabled)|(credentials)|(settings)|(default_from_address)))*$
      - name: include_fields
        in: query
        description: Whether specified fields are to be included (true) or excluded (false).
        schema:
          type: boolean
      responses:
        '200':
          description: Email provider successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEmailProviderResponseContent'
        '400':
          description: Invalid request query string. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: read:email_provider.'
        '404':
          description: Email provider has not been configured.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_provider
      x-release-lifecycle: GA
      x-operation-name: get
      x-operation-request-parameters-name: GetEmailProviderRequestParameters
      x-operation-group:
      - emails
      - provider
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:email_provider
    delete:
      summary: Delete Email Provider
      description: 'Delete the email provider.

        '
      tags:
      - emails
      responses:
        '204':
          description: The email provider has been deleted.
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation
        '403':
          description: 'Insufficient scope, expected any of: delete:email_provider'
        '404':
          description: Email provider does not exist.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: delete_provider
      x-release-lifecycle: GA
      x-operation-name: delete
      x-operation-group:
      - emails
      - provider
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - delete:email_provider
    patch:
      summary: Update Email Provider
      description: "Update an <a href=\"https://auth0.com/docs/email/providers\">email provider</a>. The <code>credentials</code> object\nrequires different properties depending on the email provider (which is specified using the <code>name</code> property):\n<ul>\n  <li><code>mandrill</code> requires <code>api_key</code></li>\n  <li><code>sendgrid</code> requires <code>api_key</code></li>\n  <li>\n    <code>sparkpost</code> requires <code>api_key</code>. Optionally, set <code>region</code> to <code>eu</code> to use\n    the SparkPost service hosted in Western Europe; set to <code>null</code> to use the SparkPost service hosted in\n    North America. <code>eu</code> or <code>null</code> are the only valid values for <code>region</code>.\n  </li>\n  <li>\n    <code>mailgun</code> requires <code>api_key</code> and <code>domain</code>. Optionally, set <code>region</code> to\n    <code>eu</code> to use the Mailgun service hosted in Europe; set to <code>null</code> otherwise. <code>eu</code> or\n    <code>null</code> are the only valid values for <code>region</code>.\n  </li>\n  <li><code>ses</code> requires <code>accessKeyId</code>, <code>secretAccessKey</code>, and <code>region</code></li>\n  <li>\n    <code>smtp</code> requires <code>smtp_host</code>, <code>smtp_port</code>, <code>smtp_user</code>, and\n    <code>smtp_pass</code>\n  </li>\n</ul>\nDepending on the type of provider it is possible to specify <code>settings</code> object with different configuration\noptions, which will be used when sending an email:\n<ul>\n  <li>\n    <code>smtp</code> provider, <code>settings</code> may contain <code>headers</code> object.\n    <ul>\n      <li>\n        When using AWS SES SMTP host, you may provide a name of configuration set in\n        <code>X-SES-Configuration-Set</code> header. Value must be a string.\n      </li>\n      <li>\n        When using Sparkpost host, you may provide value for\n        <code>X-MSYS_API</code> header. Value must be an object.\n      </li>\n    </ul>\n    for <code>ses</code> provider, <code>settings</code> may contain <code>message</code> object, where you can provide\n    a name of configuration set in <code>configuration_set_name</code> property. Value must be a string.\n  </li>\n</ul>\n"
      tags:
      - emails
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailProviderRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateEmailProviderRequestContent'
      responses:
        '200':
          description: Email provider successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEmailProviderResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: update:email_provider.'
        '404':
          description: Email provider has not been configured.
        '409':
          description: No deployed action was found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: patch_provider
      x-release-lifecycle: GA
      x-operation-name: update
      x-operation-group:
      - emails
      - provider
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:email_provider
    post:
      summary: Configure Email Provider
      description: "Create an <a href=\"https://auth0.com/docs/email/providers\">email provider</a>. The <code>credentials</code> object\nrequires different properties depending on the email provider (which is specified using the <code>name</code> property):\n<ul>\n  <li><code>mandrill</code> requires <code>api_key</code></li>\n  <li><code>sendgrid</code> requires <code>api_key</code></li>\n  <li>\n    <code>sparkpost</code> requires <code>api_key</code>. Optionally, set <code>region</code> to <code>eu</code> to use\n    the SparkPost service hosted in Western Europe; set to <code>null</code> to use the SparkPost service hosted in\n    North America. <code>eu</code> or <code>null</code> are the only valid values for <code>region</code>.\n  </li>\n  <li>\n    <code>mailgun</code> requires <code>api_key</code> and <code>domain</code>. Optionally, set <code>region</code> to\n    <code>eu</code> to use the Mailgun service hosted in Europe; set to <code>null</code> otherwise. <code>eu</code> or\n    <code>null</code> are the only valid values for <code>region</code>.\n  </li>\n  <li><code>ses</code> requires <code>accessKeyId</code>, <code>secretAccessKey</code>, and <code>region</code></li>\n  <li>\n    <code>smtp</code> requires <code>smtp_host</code>, <code>smtp_port</code>, <code>smtp_user</code>, and\n    <code>smtp_pass</code>\n  </li>\n</ul>\nDepending on the type of provider it is possible to specify <code>settings</code> object with different configuration\noptions, which will be used when sending an email:\n<ul>\n  <li>\n    <code>smtp</code> provider, <code>settings</code> may contain <code>headers</code> object.\n    <ul>\n      <li>\n        When using AWS SES SMTP host, you may provide a name of configuration set in\n        <code>X-SES-Configuration-Set</code> header. Value must be a string.\n      </li>\n      <li>\n        When using Sparkpost host, you may provide value for\n        <code>X-MSYS_API</code> header. Value must be an object.\n      </li>\n    </ul>\n  </li>\n  <li>\n    for <code>ses</code> provider, <code>settings</code> may contain <code>message</code> object, where you can provide\n    a name of configuration set in <code>configuration_set_name</code> property. Value must be a string.\n  </li>\n</ul>\n"
      tags:
      - emails
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailProviderRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateEmailProviderRequestContent'
      responses:
        '201':
          description: Email provider successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmailProviderResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: create:email_provider.'
        '409':
          description: Email provider is already configured.
          x-description-1: No deployed action was found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: post_provider
      x-release-lifecycle: GA
      x-operation-name: create
      x-operation-group:
      - emails
      - provider
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - create:email_provider
components:
  schemas:
    EmailProviderNameEnum:
      type: string
      description: Name of the email provider. Can be `mailgun`, `mandrill`, `sendgrid`, `resend`, `ses`, `sparkpost`, `smtp`, `azure_cs`, `ms365`, or `custom`.
      enum:
      - mailgun
      - mandrill
      - sendgrid
      - resend
      - ses
      - sparkpost
      - smtp
      - azure_cs
      - ms365
      - custom
    EmailSMTPHost:
      type: string
      description: SMTP host.
      anyOf:
      - type: string
        format: hostname-rfc2181
      - type: string
        format: ipv4
      - type: string
        format: ipv6
    EmailSparkPostRegionEnum:
      description: Set to <code>eu</code> to use SparkPost service hosted in Western Europe. To use SparkPost hosted in North America, set it to <code>null</code>.
      enum:
      - eu
      - null
    GetEmailProviderResponseContent:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the email provider. Can be `mailgun`, `mandrill`, `sendgrid`, `resend`, `ses`, `sparkpost`, `smtp`, `azure_cs`, `ms365`, or `custom`.
          default: sendgrid
        enabled:
          type: boolean
          description: Whether the provider is enabled (true) or disabled (false).
          default: true
        default_from_address:
          type: string
          description: Email address to use as "from" when no other address specified.
        credentials:
          $ref: '#/components/schemas/EmailProviderCredentials'
        settings:
          $ref: '#/components/schemas/EmailProviderSettings'
    EmailProviderSettings:
      type: object
      description: Specific provider setting
      additionalProperties: true
    UpdateEmailProviderResponseContent:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the email provider. Can be `mailgun`, `mandrill`, `sendgrid`, `resend`, `ses`, `sparkpost`, `smtp`, `azure_cs`, `ms365`, or `custom`.
          default: sendgrid
        enabled:
          type: boolean
          description: Whether the provider is enabled (true) or disabled (false).
          default: true
        default_from_address:
          type: string
          description: Email address to use as "from" when no other address specified.
        credentials:
          $ref: '#/components/schemas/EmailProviderCredentials'
        settings:
          $ref: '#/components/schemas/EmailProviderSettings'
    UpdateEmailProviderRequestContent:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name:
          $ref: '#/components/schemas/EmailProviderNameEnum'
        enabled:
          type: boolean
          description: Whether the provider is enabled (true) or disabled (false).
        default_from_address:
          type: string
          description: Email address to use as "from" when no other address specified.
        credentials:
          $ref: '#/components/schemas/EmailProviderCredentialsSchema'
        settings:
          $ref: '#/components/schemas/EmailSpecificProviderSettingsWithAdditionalProperties'
    EmailMailgunRegionEnum:
      description: Set to <code>eu</code> if your domain is provisioned to use Mailgun's EU region. Otherwise, set to <code>null</code>.
      enum:
      - eu
      - null
    CreateEmailProviderResponseContent:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the email provider. Can be `mailgun`, `mandrill`, `sendgrid`, `resend`, `ses`, `sparkpost`, `smtp`, `azure_cs`, `ms365`, or `custom`.
          default: sendgrid
        enabled:
          type: boolean
          description: Whether the provider is enabled (true) or disabled (false).
          default: true
        default_from_address:
          type: string
          description: Email address to use as "from" when no other address specified.
        credentials:
          $ref: '#/components/schemas/EmailProviderCredentials'
        settings:
          $ref: '#/components/schemas/EmailProviderSettings'
    EmailSpecificProviderSettingsWithAdditionalProperties:
      type:
      - object
      - 'null'
      description: Specific provider setting
      additionalProperties: true
    EmailProviderCredentials:
      type: object
      description: Credentials required to use the provider.
      additionalProperties: false
      properties:
        api_user:
          type: string
          description: API User.
        region:
          type: string
          description: AWS or SparkPost region.
        smtp_host:
          type: string
          description: SMTP host.
        smtp_port:
          type: integer
          description: SMTP port.
        smtp_user:
          type: string
          description: SMTP username.
    ExtensibilityEmailProviderCredentials:
      type: object
      additionalProperties: false
      properties: {}
    CreateEmailProviderRequestContent:
      type: object
      additionalProperties: false
      required:
      - name
      - credentials
      properties:
        name:
          $ref: '#/components/schemas/EmailProviderNameEnum'
        enabled:
          type: boolean
          description: Whether the provider is enabled (true) or disabled (false).
          default: true
        default_from_address:
          type: string
          description: Email address to use as "from" when no other address specified.
        credentials:
          $ref: '#/components/schemas/EmailProviderCredentialsSchema'
        settings:
          $ref: '#/components/schemas/EmailSpecificProviderSettingsWithAdditionalProperties'
    EmailProviderCredentialsSchema:
      type: object
      description: Credentials required to use the provider.
      anyOf:
      - type: object
        additionalProperties: false
        required:
        - api_key
        properties:
          api_key:
            type: string
            description: API Key
            minLength: 1
      - type: object
        additionalProperties: false
        minProperties: 1
        properties:
          accessKeyId:
            type: string
            description: AWS Access Key ID.
            minLength: 1
          secretAccessKey:
            type: string
            description: AWS Secret Access Key.
            minLength: 1
          region:
            type: string
            description: AWS region.
            minLength: 1
      - type: object
        additionalProperties: false
        minProperties: 1
        properties:
          smtp_host:
            $ref: '#/components/schemas/EmailSMTPHost'
          smtp_port:
            type: integer
            description: SMTP port.
          smtp_user:
            type: string
            description: SMTP username.
            minLength: 1
          smtp_pass:
            type: string
            description: SMTP password.
            minLength: 1
      - type: object
        additionalProperties: false
        minProperties: 1
        properties:
          api_key:
            type: string
            description: API Key
            minLength: 1
          region:
            $ref: '#/components/schemas/EmailSparkPostRegionEnum'
      - type: object
        additionalProperties: false
        minProperties: 1
        properties:
          api_key:
            type: string
            description: API Key
            minLength: 1
          domain:
            type: string
            description: Domain
            minLength: 4
          region:
            $ref: '#/components/schemas/EmailMailgunRegionEnum'
      - type: object
        additionalProperties: false
        minProperties: 1
        properties:
          connectionString:
            type: string
            description: Azure Communication Services Connection String.
            minLength: 1
      - type: object
        additionalProperties: false
        minProperties: 1
        properties:
          tenantId:
            type: string
            description: Microsoft 365 Tenant ID.
            minLength: 1
          clientId:
            type: string
            description: Microsoft 365 Client ID.
            minLength: 1
          clientSecret:
            type: string
            description: Microsoft 365 Client Secret.
            minLength: 1
      - $ref: '#/components/schemas/ExtensibilityEmailProviderCredentials'