Twilio SendGrid Templates API

openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Templates API
  summary: The Twilio SendGrid Templates API allows you to create and manage email
    templates to be delivered with SendGrid's sending APIs.
  description: 'The Twilio SendGrid Templates API allows you to create and manage
    email templates to be delivered with SendGrid''s sending APIs. The templates you
    create will be available using a template ID that is passed to our sending APIs
    as part of the request. Each template may then have multiple versions associated
    with it. Whichever version is set as "active" at the time of the request will
    be sent to your recipients. This system allows you to update a single template''s
    look and feel entirely without modifying your requests to our Mail Send API. For
    example, you could have a single template for welcome emails. That welcome template
    could then have a version for each season of the year that''s themed appropriately
    and marked as active during the appropriate season. The template ID passed to
    our sending APIs never needs to change; you can just modify which version is active.


    This API provides operations to create and manage your templates as well as their
    versions.


    Each user can create up to 300 different templates. Templates are specific to
    accounts and Subusers. Templates created on a parent account will not be accessible
    from the Subusers'' accounts.'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
    url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
  version: 1.0.0
  x-sendgrid:
    libraryPackage: templates
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
paths:
  /v3/templates:
    post:
      operationId: CreateTemplate
      summary: Create a transactional template.
      tags:
      - Templates
      description: '**This endpoint allows you to create a transactional template.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name for the new transactional template.
                  maxLength: 100
                generation:
                  type: string
                  description: Defines whether the template supports dynamic replacement.
                  default: legacy
                  $ref: '#/components/schemas/Generation'
              required:
              - name
              example:
                name: example_name
                generation: dynamic
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplate'
              examples:
                response:
                  value:
                    id: 733ba07f-ead1-41fc-933a-3976baa23716
                    name: example_name
                    generation: legacy
                    updated_at: '2021-04-28 13:12:46'
                    versions: []
    get:
      operationId: ListTemplate
      summary: Retrieve paged transactional templates.
      tags:
      - Templates
      description: '**This endpoint allows you to retrieve all transactional templates.**'
      parameters:
      - name: generations
        in: query
        description: Comma-delimited list specifying which generations of templates
          to return. Options are `legacy`, `dynamic` or `legacy,dynamic`.
        required: false
        schema:
          type: string
          default: legacy
          $ref: '#/components/schemas/Generations'
      - name: page_size
        in: query
        description: The number of templates to be returned in each page of results
        required: true
        schema:
          type: number
          minimum: 1
          maximum: 200
      - name: page_token
        in: query
        description: A token corresponding to a specific page of results, as provided
          by metadata
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    description: ''
                    items:
                      $ref: '#/components/schemas/TransactionalTemplatesTemplateLean'
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
              examples:
                response:
                  value:
                    result:
                    - id: fae7c985-eb92-4b47-9987-28ec29dbc698
                      name: example_name
                      generation: legacy
                      updated_at: '2020-11-12 12:00:09'
                      versions: []
                    _metadata:
                      self: https://api.sendgrid.com/v3/templates
                      count: 1
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        error_id:
                          type: string
  /v3/templates/{template_id}:
    parameters:
    - name: template_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: DuplicateTemplate
      summary: Duplicate a transactional template.
      tags:
      - Templates
      description: '**This endpoint allows you to duplicate a transactional template.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name for the new transactional template.
                  maxLength: 100
              example:
                name: example_name
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplate'
              examples:
                response:
                  value:
                    id: 733ba07f-ead1-41fc-933a-3976baa23716
                    name: example_name
                    generation: dynamic
                    updated_at: '2020-12-12 58:26:65'
                    versions: []
    get:
      operationId: GetTemplate
      summary: Retrieve a single transactional template.
      tags:
      - Templates
      description: '**This endpoint allows you to retrieve a single transactional
        template.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplate'
              examples:
                response:
                  value:
                    id: 40da60e6-66f3-4223-9406-ba58b7f55a62
                    name: Duis in dolor
                    generation: legacy
                    updated_at: '2020-12-12 58:26:65'
                    versions: []
    patch:
      operationId: UpdateTemplate
      summary: Edit a transactional template.
      tags:
      - Templates
      description: '**This endpoint allows you to edit the name of a transactional
        template.**


        To edit the template itself, [create a new transactional template version](https://docs.sendgrid.com/api-reference/transactional-templates-versions/create-a-new-transactional-template-version).'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the transactional template.
                  maxLength: 100
              example:
                name: new_example_name
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplate'
              examples:
                response:
                  value:
                    id: 733ba07f-ead1-41fc-933a-3976baa23716
                    name: new_example_name
                    generation: legacy
                    updated_at: '2021-04-28 13:12:46'
                    versions: []
    delete:
      operationId: DeleteTemplate
      summary: Delete a template.
      tags:
      - Templates
      description: '**This endpoint allows you to delete a transactional template.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /v3/templates/{template_id}/versions:
    parameters:
    - name: template_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      operationId: CreateTemplateVersion
      summary: Create a new transactional template version.
      tags:
      - Templates Versions
      description: '**This endpoint allows you to create a new version of a template.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        $ref: '#/components/requestBodies/PostPatchTransactionalTemplateVersion'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplateVersionOutput'
              examples:
                response:
                  value:
                    id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3
                    template_id: ddb96bbc-9b92-425e-8979-99464621b543
                    active: 1
                    name: example_version_name
                    html_content: <%body%>
                    plain_content: <%body%>
                    generate_plain_content: true
                    subject: <%subject%>
                    updated_at: '2019-03-13 18:56:33'
                    editor: code
  /v3/templates/{template_id}/versions/{version_id}:
    parameters:
    - name: template_id
      in: path
      description: ' The ID of the original template'
      required: true
      schema:
        type: string
        format: uuid
    - name: version_id
      in: path
      description: The ID of the template version
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: GetTemplateVersion
      summary: Retrieve a specific transactional template version.
      tags:
      - Templates Versions
      description: '**This endpoint allows you to retrieve a specific version of a
        template.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplateVersionOutput'
              examples:
                response:
                  value:
                    id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3
                    template_id: ddb96bbc-9b92-425e-8979-99464621b543
                    active: 1
                    name: example_version_name
                    html_content: <%body%>
                    plain_content: <%body%>
                    generate_plain_content: true
                    subject: <%subject%>
                    updated_at: '2019-03-13 18:56:33'
                    editor: code
    patch:
      operationId: UpdateTemplateVersion
      summary: Edit a transactional template version.
      tags:
      - Templates Versions
      description: '**This endpoint allows you to edit the content of your template
        version.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        $ref: '#/components/requestBodies/PostPatchTransactionalTemplateVersion'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplateVersionOutput'
              examples:
                response:
                  value:
                    id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3
                    template_id: ddb96bbc-9b92-425e-8979-99464621b543
                    active: 1
                    name: example_version_name
                    html_content: <%body%>
                    plain_content: <%body%>
                    generate_plain_content: true
                    subject: <%subject%>
                    updated_at: '2019-03-13 18:56:33'
                    editor: code
    delete:
      operationId: DeleteTemplateVersion
      summary: Delete a transactional template version.
      tags:
      - Templates Versions
      description: '**This endpoint allows you to delete a transactional template
        version.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '204':
          description: ''
  /v3/templates/{template_id}/versions/{version_id}/activate:
    parameters:
    - name: template_id
      in: path
      description: The ID of the original template
      required: true
      schema:
        type: string
        format: uuid
    - name: version_id
      in: path
      description: The ID of the template version
      required: true
      schema:
        type: string
        format: uuid
    post:
      operationId: ActivateTemplateVersion
      summary: Activate a transactional template version.
      tags:
      - Templates Versions
      description: '**This endpoint allows you to activate a version of one of your
        templates.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalTemplateVersionOutput'
              examples:
                response:
                  value:
                    id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3
                    template_id: ddb96bbc-9b92-425e-8979-99464621b543
                    active: 1
                    name: example_version_name
                    html_content: <%body%>
                    plain_content: <%body%>
                    generate_plain_content: true
                    subject: <%subject%>
                    updated_at: '2019-03-13 18:56:33'
                    editor: code
components:
  schemas:
    TransactionalTemplate:
      title: 'Transactional Templates: Template'
      example:
        id: 33feeff2-5069-43fe-8853-428651e5be79
        name: example_name
        updated_at: '2021-04-28 13:12:46'
        warning:
          message: Sample warning message
        generation: legacy
      type: object
      properties:
        id:
          type: string
          description: The ID of the transactional template.
          minLength: 36
          maxLength: 36
          format: uuid
        name:
          type: string
          description: The name for the transactional template.
          maxLength: 100
        generation:
          type: string
          description: Defines the generation of the template.
          $ref: '#/components/schemas/Generation1'
        updated_at:
          type: string
          description: The date and time that this transactional template version
            was updated.
          pattern: ^(\d{4}-\d{2}-\d{2}) ((\d{2}):(\d{2}):(\d{2}))$
        versions:
          type: array
          description: The different versions of this transactional template.
          items:
            $ref: '#/components/schemas/TransactionalTemplatesVersionOutputLean'
        warning:
          $ref: '#/components/schemas/TransactionalTemplateWarning'
      required:
      - generation
      - id
      - name
      - updated_at
    TransactionalTemplateVersionOutput:
      title: 'Transactional Templates: Version Output'
      type: object
      properties:
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/TransactionalTemplateWarning'
        active:
          type: integer
          description: Set the version as the active version associated with the template.
            Only one version of a template can be active. The first version created
            for a template will automatically be set to Active.
          $ref: '#/components/schemas/Active1'
        name:
          type: string
          description: Name of the transactional template version.
          maxLength: 100
        html_content:
          type: string
          description: The HTML content of the Design.
        plain_content:
          type: string
          description: Plain text content of the Design.
        generate_plain_content:
          type: boolean
          description: If true, plain_content is always generated from html_content.
            If false, plain_content is not altered.
          default: true
        subject:
          type: string
          description: Subject of the new transactional template version.
          maxLength: 255
        editor:
          type: string
          description: The editor used in the UI.
          $ref: '#/components/schemas/Editor1'
        test_data:
          type: string
          description: For dynamic templates only, the mock json data that will be
            used for template preview and test sends.
        id:
          type: string
          description: ID of the transactional template version.
          format: uuid
        template_id:
          type: string
          description: ID of the transactional template.
        updated_at:
          type: string
          description: The date and time that this transactional template version
            was updated.
        thumbnail_url:
          type: string
          description: A Thumbnail preview of the template's html content.
      required:
      - name
      - subject
    TransactionalTemplateVersionCreate:
      title: 'Transactional Templates: Version Create'
      type: object
      properties:
        active:
          type: integer
          description: Set the version as the active version associated with the template
            (0 is inactive, 1 is active). Only one version of a template can be active.
            The first version created for a template will automatically be set to
            Active.
          $ref: '#/components/schemas/Active'
        name:
          type: string
          description: Name of the transactional template version.
          maxLength: 100
        html_content:
          type: string
          description: The HTML content of the version. Maximum of 1048576 bytes allowed.
          maxLength: 1048576
        plain_content:
          type: string
          description: Text/plain content of the transactional template version. Maximum
            of 1048576 bytes allowed.
          maxLength: 1048576
          default: <generated from html_content if left empty>
        generate_plain_content:
          type: boolean
          description: If true, plain_content is always generated from html_content.
            If false, plain_content is not altered.
          default: true
        subject:
          type: string
          description: Subject of the new transactional template version.
          maxLength: 255
        editor:
          type: string
          description: The editor used in the UI.
          $ref: '#/components/schemas/Editor'
        test_data:
          type: string
          description: For dynamic templates only, the mock json data that will be
            used for template preview and test sends.
      required:
      - name
      - subject
      example:
        template_id: Excepteur Ut qui
        active: 1
        name: pariatur non incididunt commodo
        html_content: dolor
        generate_plain_content: false
        subject: aliquip nulla Ut
        editor: design
        plain_content: labore dolore
    TransactionalTemplatesVersionOutputLean:
      title: 'Transactional Templates: Version Output Lean'
      type: object
      properties:
        id:
          type: string
          description: ID of the transactional template version.
          format: uuid
        template_id:
          type: string
          description: ID of the transactional template.
        active:
          type: integer
          description: Set the version as the active version associated with the template.
            Only one version of a template can be active. The first version created
            for a template will automatically be set to Active.
          $ref: '#/components/schemas/Active1'
        name:
          type: string
          description: Name of the transactional template version.
          maxLength: 100
        subject:
          type: string
          description: Subject of the new transactional template version.
          maxLength: 255
        updated_at:
          type: string
          description: The date and time that this transactional template version
            was updated.
        generate_plain_content:
          type: boolean
          description: If true, plain_content is always generated from html_content.
            If false, plain_content is not altered.
          default: true
        html_content:
          type: string
          description: The HTML content of the Design.
        plain_content:
          type: string
          description: Plain text content of the Design.
        editor:
          type: string
          description: The editor used in the UI.
          $ref: '#/components/schemas/Editor1'
        thumbnail_url:
          type: string
          description: A Thumbnail preview of the template's html content.
    TransactionalTemplatesTemplateLean:
      title: 'Transactional Templates: Template Lean'
      type: object
      properties:
        id:
          type: string
          description: The ID of the transactional template.
          minLength: 36
          maxLength: 36
          format: uuid
        name:
          type: string
          description: The name for the transactional template.
          maxLength: 100
        generation:
          type: string
          description: Defines the generation of the template.
          $ref: '#/components/schemas/Generation1'
        updated_at:
          type: string
          description: The date and time that this transactional template version
            was updated.
          pattern: ^(\d{4}-\d{2}-\d{2}) ((\d{2}):(\d{2}):(\d{2}))$
        versions:
          type: array
          description: The different versions of this transactional template.
          items:
            $ref: '#/components/schemas/TransactionalTemplatesVersionOutputLean'
      required:
      - id
      - name
      - generation
      - updated_at
      example:
        id: 0c314114-a2b7-4523-8cbc-a293d7d19007
        name: example_name
        generation: legacy
        updated_at: '2021-04-28 13:12:46'
        versions: []
    TransactionalTemplateWarning:
      title: Warning
      type: object
      properties:
        message:
          type: string
          description: Warning message for the user
      example:
        message: A sample warning message.
    Metadata:
      title: _metadata
      type: object
      properties:
        prev:
          type: string
          format: uri
        self:
          type: string
          format: uri
        next:
          type: string
          format: uri
        count:
          type: integer
          minimum: 0
    Generation:
      type: string
      enum:
      - legacy
      - dynamic
    Generations:
      type: string
      enum:
      - legacy
      - dynamic
      - legacy,dynamic
    Active:
      type: integer
      enum:
      - 0
      - 1
    Editor:
      type: string
      enum:
      - code
      - design
    Active1:
      type: integer
      enum:
      - 0
      - 1
    Editor1:
      type: string
      enum:
      - code
      - design
    Generation1:
      type: string
      enum:
      - legacy
      - dynamic
  responses: {}
  parameters:
    OnBehalfOf:
      name: on-behalf-of
      in: header
      description: 'The `on-behalf-of` header allows you to make API calls from a
        parent account on behalf of the parent''s Subusers or customer accounts. You
        will use the parent account''s API key when using this header. When making
        a call on behalf of a customer account, the property value should be "account-id"
        followed by the customer account''s ID (e.g., `on-behalf-of: account-id <account-id>`).
        When making a call on behalf of a Subuser, the property value should be the
        Subuser''s username (e.g., `on-behalf-of: <subuser-username>`). See [**On
        Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of)
        for more information.'
      required: false
      schema:
        type: string
  examples: {}
  requestBodies:
    PostPatchTransactionalTemplateVersion:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionalTemplateVersionCreate'
  headers: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Twilio SendGrid requires you to authenticate with its APIs using
        an API key. The API key must be sent as a bearer token in the Authorization
        header.
tags:
- name: Templates
  description: Twilio SendGrid Templates API
- name: Templates Versions
  description: 'Twilio SendGrid Templates API: Versions operations'
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid