openapi: 3.0.0
info:
  title: Auth0 Authentication actions email-templates 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: email-templates
paths:
  /email-templates:
    post:
      summary: Create an Email Template
      description: Create an email template.
      tags:
      - email-templates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailTemplateRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateEmailTemplateRequestContent'
      responses:
        '200':
          description: Template successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmailTemplateResponseContent'
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
          x-description-1: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected: create:email_templates.'
        '409':
          description: Template (templateName) already exists.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: post_email-templates
      x-release-lifecycle: GA
      x-operation-name: create
      x-operation-group: emailTemplates
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - create:email_templates
  /email-templates/{templateName}:
    get:
      summary: Get an Email Template
      description: Retrieve an email template by pre-defined name. These names are `verify_email`, `verify_email_by_code`, `reset_email`, `reset_email_by_code`, `welcome_email`, `blocked_account`, `stolen_credentials`, `enrollment_email`, `mfa_oob_code`, `user_invitation`, and `async_approval`. The names `change_password`, and `password_reset` are also supported for legacy scenarios.
      tags:
      - email-templates
      parameters:
      - name: templateName
        in: path
        description: Template name. Can be `verify_email`, `verify_email_by_code`, `reset_email`, `reset_email_by_code`, `welcome_email`, `blocked_account`, `stolen_credentials`, `enrollment_email`, `mfa_oob_code`, `user_invitation`, `async_approval`, `change_password` (legacy), or `password_reset` (legacy).
        required: true
        schema:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
      responses:
        '200':
          description: Template successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEmailTemplateResponseContent'
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected: read:email_templates.'
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_email-templates_by_templateName
      x-release-lifecycle: GA
      x-operation-name: get
      x-operation-group: emailTemplates
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:email_templates
    patch:
      summary: Patch an Email Template
      description: Modify an email template.
      tags:
      - email-templates
      parameters:
      - name: templateName
        in: path
        description: Template name. Can be `verify_email`, `verify_email_by_code`, `reset_email`, `reset_email_by_code`, `welcome_email`, `blocked_account`, `stolen_credentials`, `enrollment_email`, `mfa_oob_code`, `user_invitation`, `async_approval`, `change_password` (legacy), or `password_reset` (legacy).
        required: true
        schema:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailTemplateRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateEmailTemplateRequestContent'
      responses:
        '200':
          description: Template successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEmailTemplateResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected: update:email_templates.'
        '404':
          description: Template not found and cannot be updated.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: patch_email-templates_by_templateName
      x-release-lifecycle: GA
      x-operation-name: update
      x-operation-group: emailTemplates
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:email_templates
    put:
      summary: Update an Email Template
      description: Update an email template.
      tags:
      - email-templates
      parameters:
      - name: templateName
        in: path
        description: Template name. Can be `verify_email`, `verify_email_by_code`, `reset_email`, `reset_email_by_code`, `welcome_email`, `blocked_account`, `stolen_credentials`, `enrollment_email`, `mfa_oob_code`, `user_invitation`, `async_approval`, `change_password` (legacy), or `password_reset` (legacy).
        required: true
        schema:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEmailTemplateRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SetEmailTemplateRequestContent'
      responses:
        '200':
          description: Template successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetEmailTemplateResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected: update:email_templates.'
        '404':
          description: Template not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: put_email-templates_by_templateName
      x-release-lifecycle: GA
      x-operation-name: set
      x-operation-group: emailTemplates
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:email_templates
components:
  schemas:
    EmailTemplateNameEnum:
      type: string
      description: Template name. Can be `verify_email`, `verify_email_by_code`, `reset_email`, `reset_email_by_code`, `welcome_email`, `blocked_account`, `stolen_credentials`, `enrollment_email`, `mfa_oob_code`, `user_invitation`, `async_approval`, `change_password` (legacy), or `password_reset` (legacy).
      default: verify_email
      enum:
      - verify_email
      - verify_email_by_code
      - reset_email
      - reset_email_by_code
      - welcome_email
      - blocked_account
      - stolen_credentials
      - enrollment_email
      - mfa_oob_code
      - user_invitation
      - change_password
      - password_reset
      - async_approval
    SetEmailTemplateResponseContent:
      type: object
      additionalProperties: false
      required:
      - template
      - body
      - from
      - subject
      - syntax
      - enabled
      properties:
        template:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
        body:
          type:
          - string
          - 'null'
          description: Body of the email template.
        from:
          type:
          - string
          - 'null'
          description: Senders `from` email address.
          default: sender@auth0.com
        resultUrl:
          type:
          - string
          - 'null'
          description: URL to redirect the user to after a successful action.
        subject:
          type:
          - string
          - 'null'
          description: Subject line of the email.
        syntax:
          type:
          - string
          - 'null'
          description: Syntax of the template body.
          default: liquid
        urlLifetimeInSeconds:
          type:
          - number
          - 'null'
          description: Lifetime in seconds that the link within the email will be valid for.
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether the `reset_email` and `verify_email` templates should include the user's email address as the `email` parameter in the returnUrl (true) or whether no email address should be included in the redirect (false). Defaults to true.
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the template is enabled (true) or disabled (false).
    CreateEmailTemplateRequestContent:
      type: object
      additionalProperties: false
      required:
      - template
      - body
      - from
      - subject
      - syntax
      - enabled
      properties:
        template:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
        body:
          type:
          - string
          - 'null'
          description: Body of the email template.
        from:
          type:
          - string
          - 'null'
          description: Senders `from` email address.
          default: sender@auth0.com
        resultUrl:
          type:
          - string
          - 'null'
          description: URL to redirect the user to after a successful action.
        subject:
          type:
          - string
          - 'null'
          description: Subject line of the email.
        syntax:
          type:
          - string
          - 'null'
          description: Syntax of the template body.
          default: liquid
        urlLifetimeInSeconds:
          type:
          - number
          - 'null'
          description: Lifetime in seconds that the link within the email will be valid for.
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether the `reset_email` and `verify_email` templates should include the user's email address as the `email` parameter in the returnUrl (true) or whether no email address should be included in the redirect (false). Defaults to true.
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the template is enabled (true) or disabled (false).
    GetEmailTemplateResponseContent:
      type: object
      additionalProperties: false
      properties:
        template:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
        body:
          type:
          - string
          - 'null'
          description: Body of the email template.
        from:
          type:
          - string
          - 'null'
          description: Senders `from` email address.
          default: sender@auth0.com
        resultUrl:
          type:
          - string
          - 'null'
          description: URL to redirect the user to after a successful action.
        subject:
          type:
          - string
          - 'null'
          description: Subject line of the email.
        syntax:
          type:
          - string
          - 'null'
          description: Syntax of the template body.
          default: liquid
        urlLifetimeInSeconds:
          type:
          - number
          - 'null'
          description: Lifetime in seconds that the link within the email will be valid for.
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether the `reset_email` and `verify_email` templates should include the user's email address as the `email` parameter in the returnUrl (true) or whether no email address should be included in the redirect (false). Defaults to true.
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the template is enabled (true) or disabled (false).
    UpdateEmailTemplateRequestContent:
      type: object
      additionalProperties: false
      properties:
        template:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
        body:
          type:
          - string
          - 'null'
          description: Body of the email template.
        from:
          type:
          - string
          - 'null'
          description: Senders `from` email address.
          default: sender@auth0.com
        resultUrl:
          type:
          - string
          - 'null'
          description: URL to redirect the user to after a successful action.
        subject:
          type:
          - string
          - 'null'
          description: Subject line of the email.
        syntax:
          type:
          - string
          - 'null'
          description: Syntax of the template body.
          default: liquid
        urlLifetimeInSeconds:
          type:
          - number
          - 'null'
          description: Lifetime in seconds that the link within the email will be valid for.
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether the `reset_email` and `verify_email` templates should include the user's email address as the `email` parameter in the returnUrl (true) or whether no email address should be included in the redirect (false). Defaults to true.
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the template is enabled (true) or disabled (false).
    CreateEmailTemplateResponseContent:
      type: object
      additionalProperties: false
      required:
      - template
      - body
      - from
      - subject
      - syntax
      - enabled
      properties:
        template:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
        body:
          type:
          - string
          - 'null'
          description: Body of the email template.
        from:
          type:
          - string
          - 'null'
          description: Senders `from` email address.
          default: sender@auth0.com
        resultUrl:
          type:
          - string
          - 'null'
          description: URL to redirect the user to after a successful action.
        subject:
          type:
          - string
          - 'null'
          description: Subject line of the email.
        syntax:
          type:
          - string
          - 'null'
          description: Syntax of the template body.
          default: liquid
        urlLifetimeInSeconds:
          type:
          - number
          - 'null'
          description: Lifetime in seconds that the link within the email will be valid for.
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether the `reset_email` and `verify_email` templates should include the user's email address as the `email` parameter in the returnUrl (true) or whether no email address should be included in the redirect (false). Defaults to true.
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the template is enabled (true) or disabled (false).
    UpdateEmailTemplateResponseContent:
      type: object
      additionalProperties: false
      properties:
        template:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
        body:
          type:
          - string
          - 'null'
          description: Body of the email template.
        from:
          type:
          - string
          - 'null'
          description: Senders `from` email address.
          default: sender@auth0.com
        resultUrl:
          type:
          - string
          - 'null'
          description: URL to redirect the user to after a successful action.
        subject:
          type:
          - string
          - 'null'
          description: Subject line of the email.
        syntax:
          type:
          - string
          - 'null'
          description: Syntax of the template body.
          default: liquid
        urlLifetimeInSeconds:
          type:
          - number
          - 'null'
          description: Lifetime in seconds that the link within the email will be valid for.
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether the `reset_email` and `verify_email` templates should include the user's email address as the `email` parameter in the returnUrl (true) or whether no email address should be included in the redirect (false). Defaults to true.
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the template is enabled (true) or disabled (false).
    SetEmailTemplateRequestContent:
      type: object
      additionalProperties: false
      required:
      - template
      - body
      - from
      - subject
      - syntax
      - enabled
      properties:
        template:
          $ref: '#/components/schemas/EmailTemplateNameEnum'
        body:
          type:
          - string
          - 'null'
          description: Body of the email template.
        from:
          type:
          - string
          - 'null'
          description: Senders `from` email address.
          default: sender@auth0.com
        resultUrl:
          type:
          - string
          - 'null'
          description: URL to redirect the user to after a successful action.
        subject:
          type:
          - string
          - 'null'
          description: Subject line of the email.
        syntax:
          type:
          - string
          - 'null'
          description: Syntax of the template body.
          default: liquid
        urlLifetimeInSeconds:
          type:
          - number
          - 'null'
          description: Lifetime in seconds that the link within the email will be valid for.
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether the `reset_email` and `verify_email` templates should include the user's email address as the `email` parameter in the returnUrl (true) or whether no email address should be included in the redirect (false). Defaults to true.
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the template is enabled (true) or disabled (false).