openapi: 3.2.0
info:
  title: Bird Email Templates API
  version: 1.0.0
  description: 'The Bird API: one REST API for email, SMS, WhatsApp, verification, and

    Realtime.'
servers:
- url: https://{region}.platform.bird.com
  description: 'Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.

    '
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      description: The region your organization's data is hosted in.
- url: https://platform.bird.com
  description: Region-independent endpoint for authentication and account administration.
- url: http://localhost:8080
  description: Local development.
security:
- BearerAuth: []
tags:
- name: Email Templates
  description: Reusable email templates and their versions, with stored subject, HTML, and plain-text content you manage and reference when sending.
paths:
  /v1/email/templates:
    post:
      operationId: createEmailTemplate
      summary: Create an email template
      description: 'Creates a template and its first editable draft.


        Send the template''s `slug` (the name you send the template by), an optional display name that

        defaults to the slug, a category, the authoring format (`source`), and the draft''s content in one

        or more languages. Leave the content out to start from an empty draft. A slug already used in the

        workspace returns a conflict.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateCreate'
      responses:
        '201':
          description: Email template created.
          headers:
            Idempotency-Replay:
              $ref: '#/components/headers/IdempotencyReplay'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
    get:
      operationId: listEmailTemplates
      summary: List email templates
      description: 'Returns a paginated list of email templates, newest first.


        The list covers both the workspace''s own templates and our built-in `system` templates. Use

        `scope` to get only one of the two, or leave it out to get both. When you leave it out, the

        workspace''s own templates come first, newest first, and our built-in templates fill the rest of

        the list once the workspace''s templates run out.


        Filter further by category or authoring format, or search with `q`, a case-insensitive substring

        match against the template''s slug, name, and description.


        Our built-in templates come in five visual themes. Each theme ships its own set of eight

        emails, and the sets overlap only partly. Use `theme` to see one of them. A template your

        workspace authored has no theme, so naming one returns our built-ins alone.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: email.templates.list
      parameters:
      - name: scope
        in: query
        required: false
        description: Filter by who owns the template. Use `system` for our built-in templates and `workspace` for the ones your workspace created. Leave it out to get both.
        schema:
          $ref: '#/components/schemas/TemplateScope'
      - name: category
        in: query
        required: false
        description: Return only `transactional` or `marketing` templates; omit to return both categories.
        schema:
          $ref: '#/components/schemas/EmailTemplateCategory'
      - name: source
        in: query
        required: false
        description: Return only templates authored in this format.
        schema:
          $ref: '#/components/schemas/EmailTemplateSource'
      - name: theme
        in: query
        required: false
        description: Filter by the visual theme a built-in template is designed in. Only our built-in templates have a theme, so naming one returns built-ins alone.
        schema:
          $ref: '#/components/schemas/EmailTemplateThemeFilter'
      - name: q
        in: query
        required: false
        description: A case-insensitive substring search across the template's slug, name, and description.
        schema:
          type: string
          minLength: 1
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/StartingAfter'
      - $ref: '#/components/parameters/EndingBefore'
      responses:
        '200':
          description: Paginated list of email templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
      - attio
      - cli
      - make
      - mcp
      - n8n
      - sdk
  /v1/email/templates/{template_ref}:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. On read, a built-in `system` template''s `bird_` slug also resolves here. Write operations (update, delete) accept a workspace template only, because a `system` template is immutable.

        '
      schema:
        type: string
        minLength: 1
      example: bird_welcome
    get:
      operationId: getEmailTemplate
      summary: Get an email template
      description: 'Returns a template''s metadata, language states, sendable languages, draft revision, and draft and published version IDs. Read a version''s language to retrieve content.


        Accepts a workspace template ID (`emt_…`) or a built-in `system` template''s `bird_` slug. A `system` template has `null` for the workspace, draft, revision, and timestamp fields.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      responses:
        '200':
          description: The requested email template metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
    patch:
      operationId: updateEmailTemplate
      summary: Update an email template
      description: 'Updates a template''s metadata and draft settings, such as its name or default language. Only the fields you send are changed.


        Content is not edited here: save a language on the draft version instead.


        Send the draft `revision` you last read. If someone else changed the draft first, including by saving a language, the revision is stale and the request returns a conflict so you can reload and retry.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateUpdate'
      responses:
        '200':
          description: The template with the updated metadata and draft settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
    delete:
      operationId: deleteEmailTemplate
      summary: Delete an email template
      description: 'Deletes the template and all its versions. The slug becomes available for reuse in the workspace, and the deletion cannot be undone.


        A template can''t be deleted while a broadcast that has not started sending still uses it, because a `scheduled` or `accepted` broadcast has not pinned the content it will send yet. List the broadcasts blocking a template delete to see which ones those are. A broadcast that has already started sending does not block the delete: it pinned its version when it started, so it keeps sending the content it froze.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: Email template deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/duplicate:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The source template to copy: a workspace template''s id (`emt_…`) or slug, or a built-in `system` template''s `bird_` slug. The copy is always a new workspace template.

        '
      schema:
        type: string
        minLength: 1
      example: welcome-email
    post:
      operationId: duplicateEmailTemplate
      summary: Duplicate an email template
      description: 'Creates a new template by copying an existing one: one of your workspace

        templates, or a built-in `system` template (by its `bird_` slug). The copy

        is a new template with its own id and a single editable draft seeded from

        the source''s current content. It inherits the source''s category, authoring

        format (`source`), and description. Copying a workspace template also

        carries over its default language and its missing-language policy, so the

        copy behaves like what it was copied from. The copy starts unpublished.


        By default the copy''s slug derives from the source''s slug, for example

        `welcome-email-copy`, with a numeric suffix added if that slug is already

        taken. Supply `slug` to choose your own. A slug already in use in the

        workspace returns a conflict.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateDuplicate'
      responses:
        '201':
          description: The newly created template copy.
          headers:
            Idempotency-Replay:
              $ref: '#/components/headers/IdempotencyReplay'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/preview:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template to preview: a workspace template''s id (`emt_…`) or slug, or a built-in `system` template''s `bird_` slug.

        '
      schema:
        type: string
        minLength: 1
      example: welcome-email
    post:
      operationId: getEmailTemplatePreview
      summary: Get an email template preview
      description: 'Renders a template with the sample values you supply and returns the resulting subject, HTML, and plain-text bodies: the personalized email as it will look once sent. By default it renders the current draft, so you can check your changes before you submit it. Pass `version` to preview a specific published version instead; built-in `system` templates have no versions, so `version` on a `bird_` template returns a validation error. Pass `contact` to see the email the way one of your contacts would receive it. Works for your workspace templates and built-in `system` templates. Sample `parameters` are capped at 16 KB once serialized, and personalization that is not valid or not supported returns a validation error naming what to fix.

        The response also reports what the HTML uses that mail clients remove, ignore, or render inconsistently. Each finding in `compatibility` names the pattern, the line and column it sits on, and what to use instead, and `compatibility_severity` reduces them to one word for the whole body. It is advisory: the preview renders either way.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplatePreviewRequest'
      responses:
        '200':
          description: The rendered preview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplatePreview'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/versions:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. A built-in `system` template''s `bird_` slug also resolves here, to its one permanently published version.

        '
      schema:
        type: string
        minLength: 1
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    get:
      operationId: listEmailTemplateVersions
      summary: List email template versions
      description: Returns the template's versions as a cursor page (the current draft plus all published versions), newest first. Each entry names its languages without returning their content. Templates retain every language of every submitted version, so listing their content would grow the response with the template's history. Read a single version for its content.
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/StartingAfter'
      - $ref: '#/components/parameters/EndingBefore'
      responses:
        '200':
          description: The template's versions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateVersionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/broadcasts:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. A built-in `system` template''s `bird_` slug also resolves here, but a system template can never be referenced by a broadcast, so this always returns an empty page for one.

        '
      schema:
        type: string
        minLength: 1
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    get:
      operationId: listEmailTemplateBroadcasts
      summary: List the broadcasts blocking a template delete
      description: 'Returns the broadcasts that block deleting this template, as a cursor page, newest first. Those are the ones that have not started sending, so they have not pinned the content they will send: `scheduled` and `accepted`. Clear every one of them and the delete goes through. Canceling clears either status; repointing at another template only works while the broadcast is `scheduled`, because an `accepted` broadcast is committed to send and an edit returns a conflict. A broadcast that is already sending is not listed and does not block the delete, because it froze its version when it started.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/PaginationLimit'
      - $ref: '#/components/parameters/StartingAfter'
      - $ref: '#/components/parameters/EndingBefore'
      responses:
        '200':
          description: The broadcasts blocking a delete of the template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateBroadcastList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/versions/{version_id}:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. On read, a built-in `system` template''s `bird_` slug also resolves here, to its one permanently published version. Discarding a draft requires a workspace template, because a `system` template has no draft and returns `404` `not_found_error`.

        '
      schema:
        type: string
        minLength: 1
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    - name: version_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EmailTemplateVersionID'
      example: emv_01krdgeqcxet5s7t44vh8rt9mg
    get:
      operationId: getEmailTemplateVersion
      summary: Get an email template version
      description: 'Returns a single version of an email template:


        - Its lifecycle metadata (`status`, `version_number`, `published_at`).

        - The content it froze in every language.

        - The `variables` that content expects at send time.


        Use List email template versions to enumerate the draft and published versions. Roll back an email template makes an earlier published version live again. Returns a `404 Not Found` error if the template or version does not exist in the workspace.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      responses:
        '200':
          description: Email template version object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateVersion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
    delete:
      operationId: deleteEmailTemplateVersion
      summary: Delete an email template draft
      description: 'Discards the draft''s unsaved work: its content resets to what is currently published (or to a single empty language when nothing has been published yet), so the draft matches what sends actually deliver again. Compare each language''s `content_hash` against the published version''s to see what a discard would throw away.


        The draft itself remains, ready for new edits at a bumped `revision`, and what is published never changes. Only the draft can be discarded. Addressing a published version returns a `422` `validation_error`, because published versions are permanent history.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: The draft was reset.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/versions/{version_id}/languages:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. A built-in `system` template''s `bird_` slug also resolves here, to its one permanently published version.

        '
      schema:
        type: string
        minLength: 1
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    - name: version_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EmailTemplateVersionID'
      example: emv_01krdgeqcxet5s7t44vh8rt9mg
    get:
      operationId: listEmailTemplateVersionLanguages
      summary: List a version's languages
      description: 'Returns every language the version holds, ordered by language tag, without the content itself, so listing a template with twenty-five languages stays small.


        Each entry has the language''s `revision` (send it back when you save that language) and its `content_hash`, so you can tell which languages changed since you last read them and fetch only those. Read a single language for its subject and bodies.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      responses:
        '200':
          description: The version's languages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateLanguageList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/versions/{version_id}/languages/{language}:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. On read, a built-in `system` template''s `bird_` slug also resolves here. Writing or removing a language requires a workspace template, because a `system` template has no draft to edit and returns `404` `not_found_error`.

        '
      schema:
        type: string
        minLength: 1
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    - name: version_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EmailTemplateVersionID'
      example: emv_01krdgeqcxet5s7t44vh8rt9mg
    - name: language
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/LanguageTag'
      example: pt-BR
    get:
      operationId: getEmailTemplateLanguage
      summary: Get one language of a version
      description: 'Returns one language''s content from a version (its subject and bodies) plus the `revision` to send back when saving it.


        Works on any version, including a published version whose content is frozen. Returns a `404 Not Found` error if the version does not have the language.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      responses:
        '200':
          description: The version's content for this language.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateLanguage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
    put:
      operationId: upsertEmailTemplateLanguage
      summary: Upsert one language of a draft
      description: 'Saves one language''s content on the template''s draft, creating that language if the draft does not have it yet and replacing it in full if it does. Send the same content twice and the draft ends up the same way, so a sync job or CI run needs one call rather than a create-or-edit decision.


        Saving one language leaves every other language untouched, so a template with many languages can be edited a language at a time. Send the `revision` you last read to have a concurrent edit rejected with a `409` `conflict_error` instead of silently overwritten.


        Only a draft can be saved: addressing a published version returns a `422` `validation_error`, because a published version never changes. A template holds at most 25 languages.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateLanguageUpsert'
      responses:
        '200':
          description: The saved language's new revisions and fingerprint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateLanguageSaved'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
    patch:
      operationId: updateEmailTemplateLanguage
      summary: Update one language of a draft
      description: 'Changes part of one language''s content on the template''s draft: send only the fields you are changing and the rest keep their current values. Use this to fix a subject line without resending a megabyte of HTML.


        The language must already exist on the draft. A language it does not have returns a `404` `not_found_error`. Save the language''s full content instead to create it.


        Send the `revision` you last read to have a concurrent edit rejected with a `409` `conflict_error`. Only a draft can be edited. Addressing a published version returns a `422` `validation_error`.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateLanguageUpdate'
      responses:
        '200':
          description: The edited language's new revisions and fingerprint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateLanguageSaved'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
    delete:
      operationId: deleteEmailTemplateLanguage
      summary: Delete one language from a draft
      description: 'Removes one language from the template''s draft, along with its content. Every other language is untouched, and the change takes effect for sends when you next submit.


        The draft''s current default language cannot be removed on its own. Point the default at a different language first, then remove the old one; doing it in the other order returns a `422` `validation_error`. Removing a language the draft does not have returns a `404` `not_found_error`, and only a draft can be changed, so addressing a published version also returns a `422` `validation_error`.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '204':
          description: The language was removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/versions/{version_id}/rollback:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. Rollback resets a draft, and a built-in `system` template has no draft, so its `bird_` slug returns `404` `not_found_error` here.

        '
      schema:
        type: string
        minLength: 1
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    - name: version_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EmailTemplateVersionID'
      example: emv_01krdgeqcxet5s7t44vh8rt9mh
    post:
      operationId: rollbackEmailTemplate
      summary: Roll back an email template
      description: Makes an earlier published version the live version used by sends, and replaces the draft with that version's content so editing continues from it. The change is immediate. No new version is created, and the version history is unchanged. Include the draft `revision` you last read, so the request is rejected with a conflict if someone else changed the draft first. The draft's current content is replaced. Rolling back to the currently live version is allowed and resets the draft to it. Only published versions can be rolled back to.
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateRollback'
      responses:
        '200':
          description: The template, with its draft reset to the restored version's content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
  /v1/email/templates/{template_ref}/versions/{version_id}/submit:
    parameters:
    - name: template_ref
      in: path
      required: true
      description: 'The template''s id (`emt_…`) or slug. Submit freezes a draft, and a built-in `system` template has no draft, so its `bird_` slug returns `404` `not_found_error` here.

        '
      schema:
        type: string
        minLength: 1
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    - name: version_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EmailTemplateVersionID'
      example: emv_01krdgeqcxet5s7t44vh8rt9mh
    post:
      operationId: submitEmailTemplateVersion
      summary: Submit an email template version
      description: 'Submits the template''s draft as a new immutable, numbered version and

        makes it the live version used by sends. The draft remains editable.


        Every language the draft has must have a subject and a body, and the

        default language must be present. Submission is all or nothing: an

        incomplete language rejects the request and the response reports every

        language error. A submit freezes every language the draft carries, so it

        cannot name a subset. The draft does not have to hold every language you

        plan to support: add more in a later version.


        Set `validate_only: true` to run the checks without creating a version.

        Set `expected_revision` to reject a concurrent edit. An unchanged draft is

        rejected. Submission is synchronous, and a returned `version` is live.'
      tags:
      - Email Templates
      security:
      - BearerAuth: []
      - CookieAuth: []
      x-audiences:
      - public
      - command
      x-snippet-key: none
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailTemplateSubmit'
      responses:
        '200':
          description: The submit's outcome, including the frozen version unless this was a validation run.
          headers:
            Idempotency-Replay:
              $ref: '#/components/headers/IdempotencyReplay'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailTemplateSubmitResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-surfaces:
      - cli
      - make
      - mcp
      - sdk
components:
  schemas:
    EmailTemplateLanguageList:
      type: object
      additionalProperties: false
      required:
      - data
      properties:
        data:
          type: array
          description: 'Every language the version holds, ordered by language tag, without their content. Read a single language to get its content.

            '
          items:
            $ref: '#/components/schemas/EmailTemplateLanguageSummary'
    LanguageTag:
      type: string
      minLength: 2
      maxLength: 35
      description: A language tag in BCP-47 form, for example `en` or `pt-BR`.
      example: pt-BR
    EmailTemplateSummary:
      type: object
      additionalProperties: false
      required:
      - id
      - workspace_id
      - slug
      - name
      - scope
      - status
      - category
      - source
      - theme
      - draft_version_id
      - live_version_id
      - published_version_id
      - live_version_number
      - languages
      - default_language
      - available_languages
      - description
      - last_submitted_at
      - created_at
      - updated_at
      properties:
        id:
          readOnly: true
          description: Template ID.
          $ref: '#/components/schemas/EmailTemplateID'
        workspace_id:
          readOnly: true
          description: The workspace that owns the template. Null for a built-in `system` template, which no workspace owns.
          oneOf:
          - $ref: '#/components/schemas/WorkspaceID'
          - type: 'null'
        slug:
          allOf:
          - $ref: '#/components/schemas/TemplateSlug'
          readOnly: true
          description: The name you send the template by. You can use either the slug or the id when you send. It never changes after the template is created. A built-in `system` template's slug always starts with `bird_`.
          example: welcome-email
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The template's display name, shown wherever the template is listed. You can change it any time. It defaults to the slug if you do not set one.
          example: Welcome email
        description:
          type:
          - string
          - 'null'
          description: What the template is for, in your own words. Null if you have not set one.
        scope:
          example: workspace
          $ref: '#/components/schemas/TemplateScope'
        status:
          $ref: '#/components/schemas/TemplateStatus'
        category:
          $ref: '#/components/schemas/EmailTemplateCategory'
        source:
          $ref: '#/components/schemas/EmailTemplateSource'
        theme:
          readOnly: true
          description: The visual theme a built-in template is designed in, or null for a template your workspace authored (which has no theme).
          example: null
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateTheme'
          - type: 'null'
        draft_version_id:
          readOnly: true
          description: The current editable draft version. Null for a built-in `system` template, which has no draft.
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateVersionID'
          - type: 'null'
        live_version_id:
          readOnly: true
          description: The version a send resolves to, or null if the template has never been published.
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateVersionID'
          - type: 'null'
        published_version_id:
          readOnly: true
          deprecated: true
          description: 'Deprecated: use `live_version_id` instead, which carries the same value.

            '
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateVersionID'
          - type: 'null'
        live_version_number:
          type:
          - integer
          - 'null'
          minimum: 1
          readOnly: true
          description: 'The live version''s sequential number (1, 2, 3…), the same one version history reports, or null if the template has never been published. A built-in `system` template is permanently published as version 1. A rollback moves it backwards, because it names the version that is live rather than how many exist.

            '
        available_languages:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/LanguageTag'
          description: 'The languages this template currently supports for sending, as BCP-47 tags. Empty until the template is published, because sends serve published content. This set may shrink for reasons other than editing, so read it rather than assuming it matches what was published.

            '
          example:
          - en
        default_language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: 'The language the draft defaults to. Read this language''s content when you have no particular preference for which one you want.

            '
        languages:
          type: object
          readOnly: true
          propertyNames:
            $ref: '#/components/schemas/LanguageTag'
          additionalProperties:
            $ref: '#/components/schemas/EmailTemplateLanguageState'
          description: 'Every language this template has, keyed by language tag, each with its state. Enough to show which templates need attention in a list without a request per row.

            '
          example:
            en:
              status: live
            de:
              status: draft
        last_submitted_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: 'When this template was last submitted. Null if it never has been. Only submitting moves this timestamp, so a rollback keeps reporting the last real submit.

            '
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When the template was created. Null for a built-in `system` template.
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When the template was last modified. Null for a built-in `system` template.
    EmailTemplateSubmitProblem:
      type: object
      additionalProperties: false
      description: One problem found while checking whether a version can be submitted.
      required:
      - code
      - message
      properties:
        language:
          readOnly: true
          description: 'The language this problem is about. Null when the problem is about the whole version rather than one language, for example an empty draft, or a default language the draft does not have.

            '
          oneOf:
          - $ref: '#/components/schemas/LanguageTag'
          - type: 'null'
        field:
          type:
          - string
          - 'null'
          minLength: 1
          readOnly: true
          description: 'Which field within that language has the problem, such as `subject` or `html`. Null when the problem is not about one particular field.

            '
          example: subject
        code:
          type: string
          minLength: 1
          pattern: ^E\d{5}$
          readOnly: true
          description: 'The error code a real submit would fail with. Look it up in the error catalog to see what it means and what to do about it.

            '
          example: E04051
        message:
          type: string
          minLength: 1
          readOnly: true
          description: 'What is wrong, worded so you can show it directly to whoever is authoring the template.

            '
          example: A subject is required to submit.
    EmailTemplateLanguageState:
      type: object
      additionalProperties: false
      description: 'Where one of the template''s languages stands: whether sends are using it, and whether its draft contains an unpublished edit.

        '
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/TemplateLanguageStatus'
        draft:
          type: boolean
          readOnly: true
          description: 'Whether the draft holds an edit to this language that has not been published. If this is true and the status is `live`, sends are still using the older content, and your edit goes out the next time you submit.

            '
    EmailTemplatePreviewContent:
      type: object
      additionalProperties: false
      description: 'Content to render instead of the template''s stored draft. Give it the subject and bodies you have in hand and they are rendered exactly as the draft would be, so an editor can show what a change looks like before it is saved.

        '
      properties:
        subject:
          type: string
          maxLength: 998
          description: The subject line to render.
          example: Welcome to Acme, {{ bird.contact.first_name }}!
        preview_text:
          type: string
          maxLength: 255
          description: 'The preview text to render. It is folded into the top of the HTML the same way publishing folds it, so the rendered body carries the hidden preheader a recipient''s inbox would read.

            '
          example: '{{ bird.contact.first_name }}, your order is on its way'
        html:
          type: string
          maxLength: 524288
          description: The HTML body to render.
          example: <h1>Hi {{ bird.contact.first_name }}</h1>
        text:
          type: string
          maxLength: 524288
          description: 'The plain-text body to render. Omit it and a plain-text alternative is derived from the HTML, the same way it is derived when you publish.

            '
    ContactID:
      type: string
      minLength: 1
      pattern: ^con_[0-9a-hjkmnp-tv-z]{26}$
      example: con_01krdgeqcxet5s7t44vh8rt9mg
    EmailTemplateVersionID:
      type: string
      minLength: 1
      pattern: ^emv_[0-9a-hjkmnp-tv-z]{26}$
      example: emv_01krdgeqcxet5s7t44vh8rt9mg
    EmailTemplateCreate:
      type: object
      additionalProperties: false
      description: Parameters for creating an email template and its initial draft.
      required:
      - slug
      - category
      - source
      properties:
        slug:
          allOf:
          - $ref: '#/components/schemas/TemplateSlug'
          description: 'The template''s workspace-unique handle, and a stable alternative to the template ID when sending by template. It can contain lowercase letters, numbers, hyphens, and underscores. It is fixed at creation, so pick it deliberately. Two prefixes are rejected: `bird_`, reserved for our built-in templates, and `emt_`, the template ID format, which a slug could never be distinguished from.

            '
          example: welcome-email
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: 'The template''s display name, shown wherever the template is listed. You can change it any time. It defaults to the slug if you do not set one.

            '
          example: Welcome email
        description:
          type: string
          description: What the template is for, in your own words.
          example: Sent to new customers after signup.
        category:
          $ref: '#/components/schemas/EmailTemplateCategory'
        source:
          allOf:
          - $ref: '#/components/schemas/EmailTemplateSourceWrite'
          description: 'The authoring format the template is written in, fixed at creation.

            `html` is finished markup you provide, optionally personalized with

            Liquid. Liquid supports variables, filters, and control flow such

            as `{% if %}` conditionals and `{% for %}` loops. A few constructs are

            rejected when you submit, and the error names exactly what to change:


            - Partial includes (`{% include %}`, `{% render %}`).

            - The `increment`, `decrement`, and `ifchanged` tags.

            - The `money`, `format_date`, `format_time`, `json`, `inspect`, and `type` filters.

            - Comparing against `empty`/`blank` (use `.size == 0` instead).

            - Blocks nested far deeper than real email markup needs.


            A broadcast''s template additionally cannot use a `{% for %}` loop,

            because a broadcast supplies one value per contact property, so there

            is nothing to iterate. Send with the messages API instead if the

            template needs one.

            '
        languages:
          type: object
          maxProperties: 25
          propertyNames:
            $ref: '#/components/schemas/LanguageTag'
          additionalProperties:
            $ref: '#/components/schemas/EmailTemplateLanguageContent'
          description: 'The initial draft''s content, keyed by language tag in BCP-47 form such as

            `en` or `pt-BR`. A template holds up to 25 languages, and a send picks one

            of them.


            Omit this to create an empty draft and add content later.

            '
          example:
            en:
              subject: Welcome to Acme, {{ bird.contact.first_name }}!
              html: <h1>Hi {{ bird.contact.first_name }}</h1>
        default_language:
          $ref: '#/components/schemas/LanguageTag'
          example: en
          description: 'The language a send uses when it does not name one, and the last resort when a requested language is not available. It has to be one of the languages you supply. If you leave it out, we default to `en`, unless you supply exactly one language, in which case we use that one instead. So if you supply two or more languages and `en` is not among them, you have to set this yourself.

            '
        on_missing_language:
          allOf:
          - $ref: '#/components/schemas/TemplateOnMissingLanguage'
          default: fallback
          description: 'What a send does when it asks for a language this template does not carry. Defaults to `fallback` on email.

            '
        language_source_required:
          type: boolean
          default: false
          description: 'Whether a send has to name a language. Set it to true to reject a send that names none instead of serving the default language. Pair it with `on_missing_language: fail` when every send must pick a language deliberately: on its own, `fail` is bypassed by naming no language at all. A template with this set cannot be used for a broadcast, which has no way to name one. Defaults to false.

            '
    EmailCompatibilityFinding:
      type: object
      additionalProperties: false
      description: 'One pattern in the HTML that mail clients remove, ignore, or render inconsistently.

        '
      required:
      - rule_id
      - severity
      - language
      - field
      - message
      - fix
      - partial
      - line
      - column
      - match
      - unsupported_clients
      - partial_clients
      properties:
        rule_id:
          readOnly: true
          description: The rule that produced this finding.
          $ref: '#/components/schemas/EmailCompatibilityRuleID'
        severity:
          readOnly: true
          $ref: '#/components/schemas/EmailCompatibilitySeverity'
        language:
          readOnly: true
          description: 'Which language''s content this finding is in. Null when the call covered a single language.

            '
          oneOf:
          - $ref: '#/components/schemas/LanguageTag'
          - type: 'null'
        field:
          type: string
          minLength: 1
          readOnly: true
          description: 'Which field of that language the finding is in. Always `html`; the subject and the plain-text body are not checked.

            '
          example: html
        message:
          type: string
          minLength: 1
          readOnly: true
          description: 'What is wrong and which clients it affects, worded to show to whoever is authoring the template. It covers the rule''s whole category rather than the exact text that matched, so a rule covering `<video>` and `<audio>` names both whichever one is on the line. Show `fix` and then `partial` after it.

            '
          example: '`display: flex` and `grid` don''t work in Outlook (Windows/Windows Mail).'
        fix:
          type:
          - string
          - 'null'
          minLength: 1
          readOnly: true
          description: 'What to use instead. Null when there is no drop-in alternative and the fix is a restructure.

            '
          example: Use tables for layout.
        partial:
          type:
          - string
          - 'null'
          minLength: 1
          readOnly: true
          description: 'Which clients support the feature only partly. Null when no client''s support is partial.

            '
          example: 'Partial support for `display: flex` and `grid` in Gmail (iOS/Android).'
        line:
          type: integer
          minimum: 1
          readOnly: true
          description: 'The 1-based line the pattern is on, in the HTML the containing response''s `compatibility` says it covered.

            '
          example: 14
        column:
          type: integer
          minimum: 1
          readOnly: true
          description: The 1-based column the pattern starts at, on that line.
          example: 6
        match:
          type: string
          minLength: 1
          maxLength: 256
          readOnly: true
          description: 'The source text that matched, starting at `line` and `column`: the smallest span that identifies what is wrong. Never the enclosing line. For a finding on a whole element, the span runs from the opening tag through the close tag, because the client drops the element''s content along with its markup. Cut at 256 characters, so an element holding a long body is quoted from its start rather than in full.

            '
          example: 'display: flex'
        unsupported_clients:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/EmailClientSupport'
          description: 'Every client family that does not support the feature at all, in alphabetical order by each entry''s `family`. Empty on a finding whose `message`, `fix`, and `partial` name no client. `message` names at most four families; this names all of them.

            '
        partial_clients:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/EmailClientSupport'
          description: 'Every client family that renders something other than what you wrote, in alphabetical order by each entry''s `family`. Empty when no client''s support is partial, which is also when `partial` is null. `partial` names at most four families; this names all of them.

            '
    TemplateOnMissingLanguage:
      type: string
      minLength: 1
      enum:
      - fallback
      - fail
      x-enum-varnames:
      - TemplateOnMissingLanguageFallback
      - TemplateOnMissingLanguageFail
      description: 'What a send or a preview does when it asks for a language the template

        cannot serve.


        `fallback` serves the closest match instead. It tries a broader form of the

        same language first, so a request for `pt-BR` can be served by a stocked

        `pt`, and then the template''s default language. A send never fails because a

        language is missing.


        `fail` rejects the send rather than serving a different language, for content

        where sending the wrong language is worse than not sending at all. It matches

        the requested tag or a broader form of it and refuses a sibling variant, so

        `pt-BR` is never served by `pt-PT`. A send that names no language still uses

        the default language.


        The default is per channel and stated on each channel''s own field, because

        what a wrong-language send costs differs. Where every language is separately

        reviewed and separately priced, falling back silently would send content the

        recipient did not expect at a rate the sender did not choose.

        '
      example: fallback
    EmailTemplatePreview:
      type: object
      additionalProperties: false
      description: 'A rendered preview of an email template: its subject, HTML, and plain-text bodies with the supplied sample values filled in, ready to display.

        '
      required:
      - subject
      - html
      - text
      - variables
      - language
      - compatibility
      - compatibility_severity
      properties:
        subject:
          type:
          - string
          - 'null'
          readOnly: true
          description: The rendered subject line. Null when the template has no subject.
        html:
          type:
          - string
          - 'null'
          readOnly: true
          description: The rendered HTML body. Null when the template has no HTML body.
        text:
          type:
          - string
          - 'null'
          readOnly: true
          description: 'The rendered plain-text body. Derived from the HTML when the template has no separate plain-text body, and null when it has neither.

            '
        language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: 'The language this preview rendered. It differs from the language you asked for when the template does not have that one and a close match was served instead.

            '
        variables:
          type: array
          readOnly: true
          description: 'The variables you can fill in with `parameters`. This list covers only the

            language named by `language`. A version read combines the variables from

            every language the version holds. Preview each language separately to see

            its own variables.


            Variables under the reserved `bird.` namespace are not listed here. We

            supply those values, but you can nest sample values under `bird` in

            `parameters` to preview them.

            '
          items:
            $ref: '#/components/schemas/TemplateVariable'
        compatibility_severity:
          readOnly: true
          $ref: '#/components/schemas/EmailCompatibilityReportSeverity'
        compatibility:
          type: array
          readOnly: true
          maxItems: 200
          items:
            $ref: '#/components/schemas/EmailCompatibilityFinding'
          description: 'What the previewed HTML uses that mail clients remove, ignore, or render inconsistently, in the order the patterns appear. Empty when nothing is worth reporting. Line and column count in the `content.html` you supplied, or in the template''s own HTML when you supplied none, so they address the source rather than the rendered output. Previewing a published `version` is the exception: where the stored version keeps no authored copy of a language the publish step rewrote, the positions count in that rewritten body, which no response returns. A preview renders either way. At most 200 findings come back, the first 200 in source order; `compatibility_severity` is derived from every finding the HTML produced, including any beyond those 200.

            '
    EmailTemplateCategory:
      type: string
      minLength: 1
      enum:
      - transactional
      - marketing
      description: Whether the template is for `transactional` email or `marketing` email.
    EmailTemplateDuplicate:
      type: object
      additionalProperties: false
      description: 'Optional parameters when duplicating an email template. The body may be omitted entirely to accept the defaults.

        '
      properties:
        slug:
          allOf:
          - $ref: '#/components/schemas/TemplateSlug'
          description: 'The copy''s workspace-unique handle, and the stable alternative to the template ID when sending by template. It can contain lowercase letters, numbers, hyphens, and underscores. Omit it to derive one from the source (for example, `welcome-email-copy`), with a numeric suffix if that slug is already taken. Two prefixes are rejected: `bird_`, reserved for our built-in templates, and `emt_`, the template ID format, which a slug could never be distinguished from. If you supply a slug that is already in use in the workspace, the request returns a conflict.

            '
          example: welcome-email-copy
    TemplateStatus:
      type: string
      minLength: 1
      readOnly: true
      enum:
      - draft
      - pending
      - active
      - rejected
      - inactive
      description: 'Where the template stands as a whole. The same five states on every channel.


        - `draft`: nothing has ever gone live.

        - `pending`: nothing is live and at least one language is in review.

        - `active`: at least one language is live, so something can be sent.

        - `rejected`: it was reviewed and every language was refused.

        - `inactive`: nothing is live and nothing is in review, so content was withdrawn or was blocked before anything went live.


        A template with one language live is `active` even while another is still

        drafted or refused. Read `languages` for the state of each language and its

        reason.


        Which values a channel reports follows its review model. A channel whose

        content a third party reviews uses all five. On email and SMS, where content

        goes live on publish, a template is `draft`, `active` or `inactive`, and

        `pending` and `rejected` are reserved for the review stage coming to both, so

        a template reaching either is not a breaking change.

        '
      example: active
    EmailTemplateVersionStatus:
      type: string
      minLength: 1
      readOnly: true
      enum:
      - draft
      - published
      - archived
      x-enum-varnames:
      - EmailTemplateVersionStatusDraft
      - EmailTemplateVersionStatusPublished
      - EmailTemplateVersionStatusArchived
      description: 'Whether this version is still being edited or has been published. It records

        the version''s publication history: a version that a later one replaced stays

        `published`. The template''s `live_version_id` names the version a send

        resolves to now.


        `archived` is reserved and no version carries it yet. Version retirement will

        produce it, so it is declared here ahead of that feature: a client written

        against this list today keeps working when the first archived version arrives,

        rather than the value''s arrival being a breaking change.

        '
      example: published
    EmailTemplateSourceWrite:
      type: string
      minLength: 1
      enum:
      - html
      x-enum-varnames:
      - EmailTemplateSourceWriteHtml
      description: The authoring format to create the template in. `html` is finished markup you provide, optionally personalized with Liquid; a format the API cannot author yet is refused.
    EmailTemplateSource:
      type: string
      minLength: 1
      x-extensible-enum:
      - html
      description: The authoring format the template is written in, fixed at creation. `html` is finished markup you provide, optionally personalized with Liquid.
    TemplateVariable:
      type: object
      additionalProperties: false
      description: 'A single variable slot a template fills in from the values supplied when sending. The same shape on email, SMS and WhatsApp, so reading what a template needs works the same way whichever channel you are sending on.

        '
      required:
      - key
      - type
      - required
      - constraint
      properties:
        key:
          type: string
          minLength: 1
          readOnly: true
          description: 'The key this slot is filled by. On email and SMS it is the key you set in the send''s `parameters` object. On WhatsApp it is the `name` you repeat on the matching parameter inside `components`, or, for a template whose placeholders are positional, the position itself as `1`, `2` and so on.

            '
        type:
          type: string
          minLength: 1
          readOnly: true
          x-extensible-enum:
          - code
          - ttl
          - count
          - ref
          - date
          - date_time
          - amount
          - currency
          - text
          description: 'The value type this slot accepts. Built-in SMS templates use typed slots (`code`, `amount` and the rest), each of which rejects a value that does not match its `constraint`. Email, WhatsApp and workspace SMS templates use `text`. Workspace SMS parameters must be scalar values. Open enum: treat an unrecognized value as a future type rather than an error.

            '
        required:
          type: boolean
          readOnly: true
          description: 'Whether the send must supply this variable. Omitting a required value returns `422` on email, SMS, and WhatsApp sends.

            '
        constraint:
          type: string
          minLength: 1
          readOnly: true
          description: A plain-language description of what values this variable accepts.
        sensitive:
          type: boolean
          readOnly: true
          default: false
          description: 'Whether this slot''s value is redacted from stored message content. A placeholder replaces the sensitive value in message history; transport queues can still carry the text needed for delivery.

            '
    EmailCompatibilityReportSeverity:
      type: string
      minLength: 1
      readOnly: true
      enum:
      - problem
      - warning
      - none
      x-enum-varnames:
      - EmailCompatibilityReportSeverityProblem
      - EmailCompatibilityReportSeverityWarning
      - EmailCompatibilityReportSeverityNone
      description: 'The worst severity across every finding the response was computed from, which

        is the authoritative reading: a response that caps how many findings it lists

        still accounts here for the ones it left out. Each response''s `compatibility`

        says which content it covered.


        - `problem`: at least one finding is a `problem`.

        - `warning`: every finding is a `warning`.

        - `none`: there are no findings.

        '
      example: warning
    Actor:
      type: object
      additionalProperties: false
      required:
      - id
      - type
      properties:
        id:
          type: string
          minLength: 1
          description: Actor identifier.
          example: usr_01krdgeqcxet5s7t44vh8rt9mg
        type:
          type: string
          minLength: 1
          x-extensible-enum:
          - user
          - api_key
          - oauth_token
          - system
          - sso
          - service_account
          description: 'Who or what performed the action: `user` for a member''s own session, `oauth_token` for a token issued to a caller on a member''s behalf, `api_key` for a workspace API key, `system` for our own automation, `sso` for an organization''s SSO connection, and `service_account` for a workspace''s connected Integration acting with no member behind it. Open enum: new actor types may be added over time, so treat any unrecognized value as a future type rather than an error.'
          example: user
        display_name:
          type:
          - string
          - 'null'
          readOnly: true
          description: 'The label the actor is shown under: typically a member''s name or email address, or the API key''s name. Null when it could not be resolved.

            '
    _ListEnvelope:
      type: object
      required:
      - next_cursor
      - prev_cursor
      - refresh_cursor
      properties:
        next_cursor:
          type:
          - string
          - 'null'
          description: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
          example: eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9
        prev_cursor:
          type:
          - string
          - 'null'
          description: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
          example: null
        refresh_cursor:
          type:
          - string
          - 'null'
          description: Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.
          example: eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9
    EmailTemplateLanguageSummary:
      type: object
      additionalProperties: false
      description: 'One language of a template version, without its content: enough to list what a version holds and how big each language is. Read a single language to get its content and its compatibility report.

        '
      required:
      - language
      - revision
      properties:
        language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: The language, in its canonical form.
        revision:
          type: integer
          minimum: 0
          readOnly: true
          description: 'This language''s revision counter, to send back when you save it. It counts only this language''s own changes.

            '
        content_hash:
          type:
          - string
          - 'null'
          readOnly: true
          description: 'A hash over this language''s content, prefixed with the algorithm that produced it (`sha256:`), so the algorithm can change without the field becoming ambiguous. It tells you whether a language differs without transferring the content, and is comparable only within one version of this API. Null for a language saved before fingerprints were recorded.

            '
          example: sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When this language was last saved. Null if that is not recorded.
        has_html:
          type: boolean
          readOnly: true
          description: Whether this language has an HTML body.
        has_text:
          type: boolean
          readOnly: true
          description: Whether this language has a plain-text body.
    EmailCompatibilityRuleID:
      type: string
      minLength: 1
      readOnly: true
      description: 'Which rule produced a finding.


        - `html_script`: a `<script>` tag.

        - `html_event_handlers`: a JavaScript event-handler attribute such as `onclick`.

        - `html_embedded_content`: an `<iframe>`, `<embed>`, or `<object>`.

        - `html_linked_stylesheet`: a `<link rel="stylesheet">`.

        - `css_at_import`: an `@import` rule.

        - `html_form`: a `<form>`, `<input>`, `<select>`, or `<textarea>`.

        - `html_svg`: an inline `<svg>`.

        - `html_media`: a `<video>` or `<audio>` element.

        - `css_display_flex_grid`: `display: flex` or `display: grid`, and their `inline-` forms.

        - `css_position_fixed_sticky`: `position: fixed` or `position: sticky`.

        - `css_variables_no_fallback`: a `var()` with no fallback value.

        - `css_viewport_units`: a `vh` or `vw` length.

        - `html_button`: a `<button>` element.

        - `css_math_functions`: `clamp()`, `min()`, or `max()`.

        - `css_modern_color`: `oklch()`, `oklab()`, `lch()`, or `lab()`.

        - `html_web_page_markup`: markup a web framework left behind, such as a `data-reactroot` attribute or a `__next` element id.

        '
      x-extensible-enum:
      - html_script
      - html_event_handlers
      - html_embedded_content
      - html_linked_stylesheet
      - css_at_import
      - html_form
      - html_svg
      - html_media
      - css_display_flex_grid
      - css_position_fixed_sticky
      - css_variables_no_fallback
      - css_viewport_units
      - html_button
      - css_math_functions
      - css_modern_color
      - html_web_page_markup
      example: css_display_flex_grid
    EmailTemplateLanguageSaved:
      type: object
      additionalProperties: false
      description: 'The identity, revision counters, and fingerprint of a saved language. The response does not include its content; read the language to retrieve it.

        '
      required:
      - language
      - revision
      - draft_revision
      - template_ref
      - version_id
      - compatibility
      - compatibility_severity
      properties:
        language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: 'The language that was saved, in its canonical form. Send a tag in any casing and this reports the form the template stores.

            '
        revision:
          type: integer
          minimum: 0
          readOnly: true
          description: 'This language''s new revision. Send it back on your next save of this language so a concurrent edit is caught instead of silently overwritten.

            '
        draft_revision:
          type: integer
          minimum: 0
          readOnly: true
          description: 'The draft''s new revision. Saving a language moves it, so any template update you make next must send this value instead of the revision you read before the save.

            '
        content_hash:
          type:
          - string
          - 'null'
          readOnly: true
          description: 'A hash over the language''s content as saved, prefixed with the algorithm that produced it (`sha256:`), so the algorithm can change without the field becoming ambiguous. It tells you whether a language differs without transferring the content, and is comparable only within one version of this API.

            '
          example: sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When this language was saved.
        template_ref:
          readOnly: true
          description: The template this save addressed.
          $ref: '#/components/schemas/EmailTemplateRef'
        version_id:
          readOnly: true
          description: The draft this save wrote to.
          $ref: '#/components/schemas/EmailTemplateVersionID'
        compatibility_severity:
          readOnly: true
          $ref: '#/components/schemas/EmailCompatibilityReportSeverity'
        next:
          type: array
          readOnly: true
          description: 'What to do next with this save. Present on reads that compute it: an empty list means

            there is nothing to do, and the field is absent entirely on responses that do not

            report next actions.


            A `problem` in `compatibility` routes back to this same write, with the identifiers

            to address it already on this response; a `warning` says what degrades and leaves

            the draft as it is.

            '
          items:
            $ref: '#/components/schemas/NextAction'
        compatibility:
          type: array
          readOnly: true
          maxItems: 200
          items:
            $ref: '#/components/schemas/EmailCompatibilityFinding'
          description: 'What the HTML you just saved uses that mail clients remove, ignore, or render inconsistently, in the order the patterns appear. Empty when nothing is worth reporting. Advisory: the language was saved either way, and a finding never refuses a write. Line and column count in the HTML as saved, which the language read returns as `content.html`. A partial update reports on the language in full rather than on the fields it carried, so it reads the same as the read of the same language. At most 200 findings come back, the first 200 in source order; `compatibility_severity` is derived from every finding the HTML produced, including any beyond those 200.

            '
    EmailTemplateBroadcastList:
      allOf:
      - type: object
        required:
        - data
        properties:
          data:
            type: array
            description: Page of broadcasts blocking a delete of the template, newest first.
            items:
              $ref: '#/components/schemas/EmailTemplateBroadcastSummary'
      - $ref: '#/components/schemas/_ListEnvelope'
    ErrorBody:
      type: object
      additionalProperties: false
      required:
      - type
      - code
      - name
      - message
      - doc_url
      - request_id
      properties:
        type:
          type: string
          minLength: 1
          description: Broad category for coarse client branching.
          enum:
          - auth_error
          - bad_request_error
          - billing_error
          - conflict_error
          - gone_error
          - internal_error
          - misdirected_error
          - not_found_error
          - not_implemented_error
          - payload_too_large_error
          - permission_error
          - precondition_error
          - rate_limit_error
          - service_unavailable_error
          - too_early_error
          - validation_error
        code:
          type: string
          minLength: 1
          pattern: ^E\d{5}$
          description: Opaque, stable, unique error identifier. Never reused.
        name:
          type: string
          minLength: 1
          description: Human-readable slug for log readability. Paired with code, never replaces it.
        message:
          type: string
          minLength: 1
          description: Human-readable description. Not stable; clients must not parse it.
        param:
          type: string
          minLength: 1
          description: Identifies the offending field. Omitted when not applicable.
        doc_url:
          type: string
          minLength: 1
          format: uri
          description: Stable link to the docs page for this error code.
        request_id:
          type: string
          minLength: 1
          description: Request correlation ID for support and troubleshooting. Also returned in the `X-Request-Id` response header.
        vendor_code:
          type: string
          minLength: 1
          description: 'Verbatim error code from an external system, such as an SMTP response code or a payment decline code. Present only when the code may help you resolve the error.

            '
        details:
          type: array
          description: Per-field validation errors. Present only on validation_error responses.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        remediation:
          type: string
          minLength: 1
          description: A human-readable next step to resolve this error. Present when a recovery is known.
        next:
          type: array
          description: 'The steps that resolve this error. Perform them in order, re-reading after each; a `wait` or `terminal` step is always last. Present for errors with a well-defined recovery, such as unmet preconditions and conflicts.

            '
          items:
            $ref: '#/components/schemas/NextAction'
    EmailTemplateRef:
      type: string
      minLength: 1
      readOnly: true
      description: 'The template this call addressed, as its id, even when you addressed it by slug. Send it back as `template_ref` on a follow-up call.

        '
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    EmailTemplateID:
      type: string
      minLength: 1
      pattern: ^emt_[0-9a-hjkmnp-tv-z]{26}$
      example: emt_01krdgeqcxet5s7t44vh8rt9mg
    EmailTemplateTheme:
      type: string
      minLength: 1
      x-extensible-enum:
      - arcane
      - barebone
      - matte
      - protocol
      - studio
      description: The visual theme a built-in template is designed in. Each of the catalog's five themes ships its own set of eight emails, and the sets overlap only partly, so the theme is what you choose between once you know which email you want. Only our built-in `system` templates have one.
    EmailTemplateRollback:
      type: object
      additionalProperties: false
      description: 'Parameters for rolling a template back to an earlier published version. Rolling back also replaces the draft with that version''s content, so you have to pass `revision`, the revision number of the draft you last read. If the draft has changed since you read it, that revision number is now stale, and the rollback fails with a conflict instead of overwriting the newer draft. Read the draft again to get its current revision, and try the rollback again.

        '
      required:
      - revision
      properties:
        revision:
          $ref: '#/components/schemas/EmailTemplateDraftRevision'
    EmailTemplate:
      type: object
      additionalProperties: false
      required:
      - id
      - workspace_id
      - slug
      - name
      - scope
      - status
      - category
      - source
      - theme
      - draft_version_id
      - live_version_id
      - published_version_id
      - revision
      - languages
      - default_language
      - available_languages
      - on_missing_language
      - language_source_required
      - description
      - last_submitted_at
      - created_at
      - updated_at
      properties:
        id:
          readOnly: true
          description: Template ID.
          $ref: '#/components/schemas/EmailTemplateID'
        workspace_id:
          readOnly: true
          description: The workspace that owns the template. Null for a built-in `system` template, which no workspace owns.
          oneOf:
          - $ref: '#/components/schemas/WorkspaceID'
          - type: 'null'
        slug:
          allOf:
          - $ref: '#/components/schemas/TemplateSlug'
          readOnly: true
          description: The name you send the template by. You can use either the slug or the id when you send. It never changes after the template is created. A built-in `system` template's slug always starts with `bird_`.
          example: welcome-email
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The template's display name, shown wherever the template is listed. You can change it any time. It defaults to the slug if you do not set one.
          example: Welcome email
        description:
          type:
          - string
          - 'null'
          description: What the template is for, in your own words. Null if you have not set one.
        scope:
          example: workspace
          $ref: '#/components/schemas/TemplateScope'
        status:
          $ref: '#/components/schemas/TemplateStatus'
        category:
          $ref: '#/components/schemas/EmailTemplateCategory'
        source:
          $ref: '#/components/schemas/EmailTemplateSource'
        theme:
          readOnly: true
          description: The visual theme a built-in template is designed in, or null for a template your workspace authored (which has no theme).
          example: null
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateTheme'
          - type: 'null'
        draft_version_id:
          readOnly: true
          description: The current editable draft version. Null for a built-in `system` template, which has no draft.
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateVersionID'
          - type: 'null'
        live_version_id:
          readOnly: true
          description: 'The version a send resolves to, or null if the template has never been published.

            '
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateVersionID'
          - type: 'null'
        published_version_id:
          readOnly: true
          deprecated: true
          description: 'Deprecated: use `live_version_id` instead, which carries the same value.

            '
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateVersionID'
          - type: 'null'
        revision:
          type:
          - integer
          - 'null'
          readOnly: true
          minimum: 0
          description: The draft's revision counter. Send it back on the next update to detect concurrent edits. Null for a built-in `system` template, which is unversioned.
        languages:
          type: object
          readOnly: true
          propertyNames:
            $ref: '#/components/schemas/LanguageTag'
          additionalProperties:
            $ref: '#/components/schemas/EmailTemplateLanguageState'
          description: 'Every language this template has, keyed by language tag in BCP-47 form

            such as `en` or `pt-BR`, each with its state. One read tells you which

            languages are live and which have unpublished edits, without fetching any

            content.


            Content is not here: read a version''s languages for that, one language at

            a time.

            '
          example:
            en:
              status: live
            pt-BR:
              status: live
              draft: true
            de:
              status: draft
        default_language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: 'The language the draft defaults to. This is the language `languages` is

            keyed against while you edit, and the language used by sends once you

            submit this draft.


            Until then sends keep using the live version''s default, so this can

            differ from what is being sent right now. `available_languages` describes

            the live version for the same reason; read a version to see the default a

            send currently uses.

            '
        available_languages:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/LanguageTag'
          description: 'The languages this template currently supports for sending, as BCP-47 tags. Empty until the template is published, because sends serve published content. The set may shrink for reasons other than editing, so read it rather than assuming it matches what was published. A built-in `system` template has no publish step and always reports its one language.

            '
          example:
          - en
        on_missing_language:
          allOf:
          - $ref: '#/components/schemas/TemplateOnMissingLanguage'
          readOnly: true
          description: 'What a send does when it asks for a language this template does not carry. Defaults to `fallback` on email.

            '
        language_source_required:
          type: boolean
          readOnly: true
          description: 'Whether a send has to name a language. When true, a send that names none is rejected instead of being served the default language, and the template cannot be used for a broadcast, which has no way to name one.

            '
        last_submitted_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: 'When this template was last submitted. Null if it never has been. Submitting is the only thing that moves this timestamp: rolling back changes which version is live without counting as a submit, so this keeps reporting the last real submit. Read it alongside `languages`, which says where each language stands.

            '
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When the template was created. Null for a built-in `system` template.
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When the template was last modified. Null for a built-in `system` template.
    EmailTemplateSubmitResult:
      type: object
      additionalProperties: false
      description: 'The outcome of a submit. This has the same shape whether the submit was a validation run or a real one, so you can read `valid` and `version` the same way either time to see what happened.

        '
      required:
      - valid
      - errors
      - template_ref
      - version_id
      - compatibility
      - compatibility_severity
      properties:
        valid:
          type: boolean
          readOnly: true
          description: Whether the version passed every check.
        errors:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/EmailTemplateSubmitProblem'
          description: 'Every problem found across the draft''s languages. Empty when `valid` is `true`.

            '
        version:
          readOnly: true
          description: 'The version this submit created, or null when it was only a validation run and nothing got frozen. As soon as this is not null, sends already use that version. No further action is required to make it live.

            '
          oneOf:
          - $ref: '#/components/schemas/EmailTemplateVersion'
          - type: 'null'
        template_ref:
          readOnly: true
          description: The template this submit addressed.
          $ref: '#/components/schemas/EmailTemplateRef'
        version_id:
          readOnly: true
          description: 'The draft this submit addressed: the one it froze, or on a validation run the one it checked and left as it was. The frozen version, when there is one, is `version`.

            '
          $ref: '#/components/schemas/EmailTemplateVersionID'
        compatibility_severity:
          readOnly: true
          $ref: '#/components/schemas/EmailCompatibilityReportSeverity'
        compatibility:
          type: array
          readOnly: true
          maxItems: 200
          items:
            $ref: '#/components/schemas/EmailCompatibilityFinding'
          description: 'What the draft''s HTML uses that mail clients remove, ignore, or render inconsistently, across every language, in alphabetical order of language tag and then the order the patterns appear. Empty when nothing is worth reporting. Advisory, and separate from `errors`: a finding never fails a submit, so the version froze either way. Each finding names the `language` it is in, and its line and column count in that language''s HTML, which the language read returns as `content.html`. At most 200 findings come back, the first 200 in that order, so a draft that reaches the cap can omit a later language''s findings entirely rather than trimming each language: read a language''s own findings from its read or its write. `compatibility_severity` is derived from every finding the draft produced, including any beyond those 200.

            '
    NextAction:
      type: object
      additionalProperties: false
      required:
      - kind
      - description
      properties:
        kind:
          type: string
          minLength: 1
          x-extensible-enum:
          - operation
          - external
          - wait
          - terminal
          description: "What you do about this step.\n\n- `operation`: call the operation named in `operation`, then\n  read again.\n- `external`: act somewhere this API does not reach, then read\n  again.\n- `wait`: nothing is asked of you, so read again later.\n- `terminal`: nothing you do resolves this, so stop retrying.\n\nTolerate a value you do not recognize: show the `description` and\noffer no action.\n"
        description:
          type: string
          minLength: 1
          description: A short, human-readable label for the step, suitable for display.
        operation:
          type: string
          minLength: 1
          description: 'The operationId to call. Present only when `kind` is `operation`. The operation''s own schema says how to call it; this says only which one, and what to address it with.

            '
        params:
          type: object
          additionalProperties:
            type: string
            minLength: 1
          description: 'The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation''s own schema and never appears here.

            '
        url:
          type: string
          format: uri
          description: 'A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal.

            '
    EmailTemplatePreviewRequest:
      type: object
      additionalProperties: false
      description: 'Sample values and options for rendering a template preview. Omit the body entirely to preview the current draft: `bird.contact.` tokens then fill from stand-in values, and a parameter you give no value for renders as empty.

        '
      properties:
        content:
          allOf:
          - $ref: '#/components/schemas/EmailTemplatePreviewContent'
          description: 'Render this content rather than the template''s stored draft. It is what an editor uses to show a change as it is made, since nothing has to be saved first.


            The content is treated exactly as a draft would be: personalization is filled in the same way, a plain-text body is derived from the HTML when you omit it, and content that could not be published is refused with the same error. `version` asks for a published version''s own content, so the two cannot be combined.

            '
        parameters:
          type: object
          additionalProperties: true
          description: 'Sample values for the variables the template uses, for this one preview only. A variable takes its value under its own name. A `bird.` value nests to match the token, so `{"bird": {"contact": {"first_name": "Ada"}}}` fills `{{ bird.contact.first_name }}`.


            A preview is more forgiving than a send: a parameter you leave out renders as empty here rather than being rejected. `parameters` is capped at 16 KB once serialized.

            '
          example:
            bird:
              contact:
                first_name: Ada
            animal: otter
        contact:
          allOf:
          - $ref: '#/components/schemas/ContactID'
          description: 'Render the template the way this contact would receive it. Every `{{ bird.contact.… }}` token takes its value from the contact''s record, narrowed to the attributes the template reads and filled from each property''s `fallback_value` where the contact holds no value: the same values a broadcast to this contact would send.


            Values are read as the contact stands right now, so a preview reflects an edit to their record as soon as you make it. A `bird.contact.…` value you also pass in `parameters` wins for that one attribute, so you can preview a contact with one field changed without editing them.

            '
        language:
          $ref: '#/components/schemas/LanguageTag'
          description: 'Which of the template''s languages to render. Omit it to render the default language. When the template does not have the language you ask for, its own `on_missing_language` setting decides whether a close match is rendered instead or the request is rejected. It is the same choice the send makes.

            '
        version:
          allOf:
          - $ref: '#/components/schemas/EmailTemplateVersionID'
          description: 'Preview a specific published version by its id, instead of the current draft.

            '
    EmailClientFamily:
      type: string
      minLength: 1
      readOnly: true
      description: 'Which mail client a finding applies to. A finding''s `message` names at most

        Apple Mail, Gmail, Outlook, and Yahoo; its `unsupported_clients` and

        `partial_clients` name every client affected.


        - `gmail`: Gmail

        - `outlook`: Outlook

        - `yahoo`: Yahoo

        - `apple_mail`: Apple Mail

        - `aol`: AOL

        - `thunderbird`: Mozilla Thunderbird

        - `samsung_email`: Samsung Email

        - `sfr`: SFR

        - `orange`: Orange

        - `protonmail`: ProtonMail

        - `hey`: HEY

        - `mail_ru`: Mail.ru

        - `fastmail`: Fastmail

        - `laposte`: LaPoste.net

        - `gmx`: GMX

        - `web_de`: WEB.DE

        - `ionos_1and1`: 1&1

        - `wp_pl`: WP.pl

        '
      x-extensible-enum:
      - gmail
      - outlook
      - yahoo
      - apple_mail
      - aol
      - thunderbird
      - samsung_email
      - sfr
      - orange
      - protonmail
      - hey
      - mail_ru
      - fastmail
      - laposte
      - gmx
      - web_de
      - ionos_1and1
      - wp_pl
      example: outlook
    EmailTemplateLanguage:
      type: object
      additionalProperties: false
      description: 'One language of a template version: its content plus the identity a concurrent-edit check needs. Reading a language returns everything you need to edit it and save it back.

        '
      required:
      - language
      - revision
      - compatibility
      - compatibility_severity
      properties:
        language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: 'The language this content belongs to, in its canonical form. Send a tag in any casing and this reports the form the template stores.

            '
        revision:
          type: integer
          minimum: 0
          readOnly: true
          description: 'This language''s revision counter. Send it back when you save this language so a concurrent edit is caught instead of silently overwritten. It counts only this language''s own changes, so editing another language never invalidates it.

            '
        content_hash:
          type:
          - string
          - 'null'
          readOnly: true
          description: 'A hash over this language''s content, prefixed with the algorithm that produced it (`sha256:`), so the algorithm can change without the field becoming ambiguous. It tells you whether a language differs without transferring the content, and is comparable only within one version of this API. Null for a language saved before fingerprints were recorded.

            '
          example: sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When this language was last saved. Null if that is not recorded.
        content:
          $ref: '#/components/schemas/EmailTemplateLanguageContent'
        compatibility_severity:
          readOnly: true
          $ref: '#/components/schemas/EmailCompatibilityReportSeverity'
        compatibility:
          type: array
          readOnly: true
          maxItems: 200
          items:
            $ref: '#/components/schemas/EmailCompatibilityFinding'
          description: 'What the stored HTML uses that mail clients remove, ignore, or render inconsistently, in the order the patterns appear. Empty when nothing is worth reporting. Line and column count in the `content.html` this response carries. At most 200 findings come back, the first 200 in source order; `compatibility_severity` is derived from every finding the HTML produced, including any beyond those 200.

            '
    EmailCompatibilitySeverity:
      type: string
      minLength: 1
      readOnly: true
      enum:
      - problem
      - warning
      x-enum-varnames:
      - EmailCompatibilitySeverityProblem
      - EmailCompatibilitySeverityWarning
      description: 'What a finding costs you.


        - `problem`: the pattern does nothing at all. The client removes the markup, never loads the stylesheet carrying it, or will not operate the control. Where a finding names clients, that is what happens in those clients.

        - `warning`: it does something, but not what you wrote.


        Neither one refuses a save, a submit, or a send.

        '
      example: warning
    EmailBroadcastStatus:
      type: string
      minLength: 1
      enum:
      - draft
      - scheduled
      - accepted
      - sending
      - sent
      - canceling
      - canceled
      - failed
      description: 'Where the broadcast itself has got to. This is separate from what happened to individual recipients, which the broadcast''s own `sent_count`, `delivered_count`, `bounced_count` and `complained_count` tell you. Those four are fields on the broadcast, not on everything that carries this status, and reading the broadcast''s recipients or its events gives the same outcomes one recipient at a time.


        - `draft`: Created, and not sent or scheduled yet.

        - `scheduled`: Due to send at `scheduled_at`. You can still edit it, and you can still change the time, right up until sending starts.

        - `accepted`: Taken for immediate sending. Nothing has gone out yet.

        - `sending`: On its way. Some recipients have been sent to and some have not.

        - `sent`: Every recipient has been sent to.

        - `canceling`: A cancellation is under way and the remaining sends are stopping.

        - `canceled`: The cancellation finished. Anything already on its way to a recipient when you canceled cannot be pulled back.

        - `failed`: The broadcast could not be sent. Reading the broadcast gives `failure_reason`, which says why. If it had already started sending, the recipients it reached keep their delivery status and carry on producing events.


        A draft is deleted rather than canceled, because it was never sent.

        '
    EmailTemplateVersionList:
      allOf:
      - type: object
        required:
        - data
        properties:
          data:
            type: array
            description: 'One page of the template''s versions, newest first. Each entry describes a version and which languages it holds. Read a single version if you want its actual content.

              '
            items:
              $ref: '#/components/schemas/EmailTemplateVersionSummary'
      - $ref: '#/components/schemas/_ListEnvelope'
    EmailTemplateList:
      allOf:
      - type: object
        required:
        - data
        properties:
          data:
            type: array
            description: Page of email templates.
            items:
              $ref: '#/components/schemas/EmailTemplateSummary'
      - $ref: '#/components/schemas/_ListEnvelope'
    TemplateScope:
      type: string
      minLength: 1
      readOnly: true
      enum:
      - system
      - workspace
      description: 'Whether the template is one of our built-in templates (`system`) or one your workspace created (`workspace`).

        '
    EmailTemplateLanguageUpsert:
      type: object
      additionalProperties: false
      description: 'Content to save for one language, replacing whatever that language held. Send every field you want the language to keep: a field you omit is cleared, which is what makes saving the same content twice land the same way every time.

        '
      required:
      - subject
      properties:
        subject:
          type: string
          minLength: 1
          maxLength: 998
          description: The email subject line for this language.
          example: Welcome to Acme, {{ bird.contact.first_name }}!
        preview_text:
          type: string
          maxLength: 255
          description: 'The line an inbox shows after the subject in the message list. Leave it out and the inbox shows the opening words of the body instead.

            '
          example: '{{ bird.contact.first_name }}, your order is on its way'
        html:
          type: string
          maxLength: 524288
          description: The HTML body for this language.
          example: <h1>Hi {{ bird.contact.first_name }}</h1>
        text:
          type: string
          maxLength: 524288
          description: 'The plain-text body for this language. Omit it and a plain-text alternative is derived from the HTML when you submit.

            '
        revision:
          type: integer
          minimum: 0
          description: 'The revision you last read for this language, to detect a concurrent edit. The save is rejected with a conflict if the language moved on since. Omit it to save unconditionally. Creating a language does not need one.

            '
    EmailTemplateLanguageUpdate:
      type: object
      additionalProperties: false
      minProperties: 1
      description: 'A partial edit to one language: send only the fields you are changing, and the rest keep their current values. The language must already exist. Create it by saving its full content instead.

        '
      properties:
        subject:
          type: string
          minLength: 1
          maxLength: 998
          description: A new email subject line for this language.
          example: Welcome to Acme, {{ bird.contact.first_name }}!
        preview_text:
          type:
          - string
          - 'null'
          maxLength: 255
          description: 'A new line for the inbox to show after the subject in the message list. Send null to clear it, and the inbox shows the opening words of the body instead.

            '
          example: '{{ bird.contact.first_name }}, your order is on its way'
        html:
          type: string
          maxLength: 524288
          description: A new HTML body for this language.
          example: <h1>Hi {{ bird.contact.first_name }}</h1>
        text:
          type:
          - string
          - 'null'
          maxLength: 524288
          description: 'A new plain-text body for this language. Send null to clear it, and a plain-text alternative is derived from the HTML when you submit.

            '
        revision:
          type: integer
          minimum: 0
          description: 'The revision you last read for this language, to detect a concurrent edit. The edit is rejected with a conflict if the language moved on since. Omit it to apply the edit unconditionally.

            '
    EmailBroadcastID:
      type: string
      minLength: 1
      pattern: ^eb_[0-9a-hjkmnp-tv-z]{26}$
      example: eb_01krdgeqcxet5s7t44vh8rt9mg
    EmailTemplateUpdate:
      type: object
      additionalProperties: false
      description: 'Partial update of a template''s metadata and draft settings. Only the fields you send are changed. The rest are left as-is. Include the draft `revision` you last read so concurrent edits are detected. Content is not here: save a language on the draft version to change what the template says.

        '
      required:
      - revision
      properties:
        revision:
          $ref: '#/components/schemas/EmailTemplateDraftRevision'
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: 'New display name, in free text. The slug stays fixed at creation, so renaming the template does not break whatever refers to it by slug or id.

            '
        description:
          type:
          - string
          - 'null'
          description: What the template is for, in your own words. Send `null` to clear it.
        default_language:
          $ref: '#/components/schemas/LanguageTag'
          description: 'New default language for the draft. Must be one of the languages the draft already has, so add the language first if it is not there yet.

            '
        on_missing_language:
          allOf:
          - $ref: '#/components/schemas/TemplateOnMissingLanguage'
          description: 'What a send does when it asks for a language this template does not carry.

            '
        language_source_required:
          type: boolean
          description: 'Whether a send has to name a language. Turning it on rejects a send that names none instead of serving the default language, and makes the template unusable for a broadcast, which has no way to name one.

            '
    EmailTemplateDraftRevision:
      type: integer
      minimum: 0
      description: 'The draft revision you last read (from the template''s `revision` field). A stale value returns a conflict so you can reload and retry.

        '
      example: 3
    EmailClientSupport:
      type: object
      additionalProperties: false
      description: 'One mail client family a finding applies to, and which of that family''s platforms.

        '
      required:
      - family
      - platforms
      properties:
        family:
          readOnly: true
          $ref: '#/components/schemas/EmailClientFamily'
        platforms:
          type: array
          minItems: 1
          readOnly: true
          items:
            $ref: '#/components/schemas/EmailClientPlatform'
          description: 'Which of the family''s platforms this applies to, in alphabetical order.

            '
          example:
          - windows
          - windows_mail
    WorkspaceID:
      type: string
      minLength: 1
      pattern: ^ws_[0-9a-hjkmnp-tv-z]{26}$
      example: ws_01krdgeqcxet5s7t44vh8rt9mg
    EmailClientPlatform:
      type: string
      minLength: 1
      readOnly: true
      description: 'Which build of a client family a finding applies to. A family can support a

        feature in one build and not another, so Gmail on iOS is tracked separately

        from Gmail on the web.


        - `desktop_webmail`: Desktop Webmail

        - `mobile_webmail`: Mobile Webmail

        - `ios`: iOS

        - `android`: Android

        - `windows`: Windows

        - `macos`: macOS

        - `windows_mail`: Windows Mail

        - `outlook_com`: Outlook.com

        '
      x-extensible-enum:
      - desktop_webmail
      - mobile_webmail
      - ios
      - android
      - windows
      - macos
      - windows_mail
      - outlook_com
      example: windows
    EmailTemplateLanguageContent:
      type: object
      additionalProperties: false
      description: 'One language''s content for an email template. Each language carries its own subject, preview text and bodies, so a translation can differ in wording and length from every other language without affecting them.

        '
      properties:
        subject:
          type: string
          maxLength: 998
          description: The email subject line for this language.
          example: Welcome to Acme, {{ bird.contact.first_name }}!
        preview_text:
          type: string
          maxLength: 255
          description: 'The line an inbox shows after the subject in the message list, for this language. Leave it out and the inbox shows the opening words of the body instead. A mail client only reads it from the message body, so publishing folds it into the top of the HTML, hidden from view once the message is open; write it here rather than hiding your own copy in the body.

            '
          example: '{{ bird.contact.first_name }}, your order is on its way'
        html:
          type: string
          maxLength: 524288
          description: The HTML body for this language.
          example: <h1>Hi {{ bird.contact.first_name }}</h1>
        text:
          type: string
          maxLength: 524288
          description: 'The plain-text body for this language. Omit it and a plain-text alternative is derived from the HTML when you submit.

            '
    EmailTemplateBroadcastSummary:
      type: object
      additionalProperties: false
      description: One broadcast that blocks deleting this template.
      required:
      - id
      - status
      - created_at
      properties:
        id:
          readOnly: true
          description: Broadcast ID.
          $ref: '#/components/schemas/EmailBroadcastID'
        status:
          readOnly: true
          description: 'Where the broadcast has got to. Only `scheduled` and `accepted` appear here: those are the two that have not pinned their content yet, so they are the ones blocking the delete. This list carries the status alone; the per-recipient totals live on the broadcast itself.

            '
          example: scheduled
          allOf:
          - $ref: '#/components/schemas/EmailBroadcastStatus'
        scheduled_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When the broadcast is due to send, or null when it is not scheduled.
          example: '2026-07-03T09:00:00Z'
        created_at:
          type: string
          minLength: 1
          format: date-time
          readOnly: true
          description: When the broadcast was created.
          example: '2026-07-01T00:00:00Z'
    EmailTemplateVersion:
      type: object
      additionalProperties: false
      required:
      - id
      - template_id
      - status
      - revision
      - variables
      - languages
      - default_language
      - created_at
      properties:
        id:
          readOnly: true
          description: Template version ID.
          $ref: '#/components/schemas/EmailTemplateVersionID'
        template_id:
          readOnly: true
          description: The template this version belongs to.
          $ref: '#/components/schemas/EmailTemplateID'
        version_number:
          type:
          - integer
          - 'null'
          minimum: 1
          readOnly: true
          description: Sequential published-version number (1, 2, 3…). Null while the version is a draft.
        status:
          $ref: '#/components/schemas/EmailTemplateVersionStatus'
        revision:
          type: integer
          minimum: 0
          readOnly: true
          description: The version's revision counter.
        variables:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/TemplateVariable'
          description: 'Every variable this version''s content uses. You supply a value for each of them when you send.


            The list combines all the languages, because languages do not have to use the same variables: if the English body uses `discount_code` and the French body uses `shipping_date`, both appear here. Send a value for every variable in the list rather than only the ones you expect the language you are sending to use. A language that does not use a variable ignores the value you sent for it, and a variable the sent language does use but you left out is rejected with a `422` naming it.


            Variables under the reserved `bird.` namespace are not listed here. We fill those in ourselves from the recipient''s contact record.

            '
        languages:
          type: object
          readOnly: true
          propertyNames:
            $ref: '#/components/schemas/LanguageTag'
          additionalProperties:
            $ref: '#/components/schemas/EmailTemplateLanguageContent'
          description: 'The content this version holds, keyed by language tag in BCP-47 form such as `en` or `pt-BR`. Publishing freezes every language together, so a version shows exactly what it would send in each of them. On a published version this is the send content.

            '
        default_language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: 'The language this version treats as its default: the one a send uses when it names none, and the last resort when a requested language is not available.

            '
        created_at:
          type: string
          minLength: 1
          format: date-time
          readOnly: true
          description: When this version was created.
        published_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When this version was published, or null if it has not been published.
        updated_by:
          oneOf:
          - $ref: '#/components/schemas/Actor'
          - type: 'null'
          readOnly: true
          description: 'Who last saved this version: a member''s own session, an OAuth token delegated from one, or a workspace API key. Publishing freezes a version, so on a published one this is whoever published it. Null means no actor is on record: a built-in template, which is code-defined rather than stored, or a version last saved by an API key before this field existed. Every other version has one, even when its display_name could not be resolved (a member whose account is gone, say).

            '
    ErrorDetail:
      type: object
      additionalProperties: false
      required:
      - param
      - message
      properties:
        param:
          type: string
          minLength: 1
          description: 'Dotted field path, such as `to[0].email`, `subject`, or `.`. When the request was rejected for a query parameter the endpoint does not declare, this carries that parameter''s name instead of a field path.

            '
        message:
          type: string
          minLength: 1
          description: What is wrong with this field.
    EmailTemplateVersionSummary:
      type: object
      additionalProperties: false
      description: 'One version of a template, without its content. Version history lists every version a template has ever had, and each one has a full copy of the content in every language it was published with. The listing describes the versions; read a single version to get what it holds.

        '
      required:
      - id
      - template_id
      - status
      - revision
      - variables
      - default_language
      - available_languages
      - created_at
      properties:
        id:
          readOnly: true
          description: Template version ID.
          $ref: '#/components/schemas/EmailTemplateVersionID'
        template_id:
          readOnly: true
          description: The template this version belongs to.
          $ref: '#/components/schemas/EmailTemplateID'
        version_number:
          type:
          - integer
          - 'null'
          minimum: 1
          readOnly: true
          description: Sequential published-version number (1, 2, 3…). Null while the version is a draft.
        status:
          $ref: '#/components/schemas/EmailTemplateVersionStatus'
        revision:
          type: integer
          minimum: 0
          readOnly: true
          description: The version's revision counter.
        variables:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/TemplateVariable'
          description: 'Every variable this version''s content uses. You supply a value for each of them when you send.


            The list combines all the languages, because languages do not have to use the same variables: if the English body uses `discount_code` and the French body uses `shipping_date`, both appear here. Send a value for every variable in the list rather than only the ones you expect the language you are sending to use. A language that does not use a variable ignores the value you sent for it, and a variable the sent language does use but you left out is rejected with a `422` naming it.


            Variables under the reserved `bird.` namespace are not listed here. We fill those in ourselves from the recipient''s contact record.

            '
        default_language:
          $ref: '#/components/schemas/LanguageTag'
          readOnly: true
          description: 'The language this version treats as its default: the one a send uses when it names none, and the last resort when a requested language is not available.

            '
        available_languages:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/LanguageTag'
          description: 'The languages this version holds, as BCP-47 tags: the keys its `languages` map would return, without the content itself.

            '
          example:
          - en
          - pt-BR
        created_at:
          type: string
          minLength: 1
          format: date-time
          readOnly: true
          description: When this version was created.
        published_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
          description: When this version was published, or null if it has not been published.
        updated_by:
          oneOf:
          - $ref: '#/components/schemas/Actor'
          - type: 'null'
          readOnly: true
          description: 'Who last saved this version: a member''s own session, an OAuth token delegated from one, or a workspace API key. Publishing freezes a version, so on a published one this is whoever published it. Null means no actor is on record: a built-in template, which is code-defined rather than stored, or a version last saved by an API key before this field existed. Every other version has one, even when its display_name could not be resolved (a member whose account is gone, say).

            '
    EmailTemplateThemeFilter:
      type: string
      enum:
      - arcane
      - barebone
      - matte
      - protocol
      - studio
      description: Filter by the visual theme a built-in template is designed in. Only built-in `system` templates have a theme, so naming one returns built-ins alone.
    TemplateLanguageStatus:
      type: string
      minLength: 1
      readOnly: true
      x-extensible-enum:
      - draft
      - live
      - superseded
      description: 'Status of one template language on channels without third-party review.


        - `draft`: it has never been published.

        - `live`: it is available to sends.

        - `superseded`: a later version replaced it.


        Treat an unknown value as not sendable.

        '
      example: live
    Error:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
    EmailTemplateSubmit:
      type: object
      additionalProperties: false
      description: 'Options for a submit. Every field here is optional, so an empty request body submits the draft exactly as it stands.

        '
      properties:
        validate_only:
          type: boolean
          default: false
          description: 'Check the draft without actually submitting it. Every language gets checked and every problem gets reported back to you, but nothing is frozen and no new version gets created. Give a validation run its own `Idempotency-Key`, separate from the real submit that follows it. You can also send no key. The validation request and real submit have different bodies, so using the same key for both is rejected as key reuse.

            '
        expected_revision:
          $ref: '#/components/schemas/EmailTemplateDraftRevision'
        languages:
          type: array
          minItems: 1
          maxItems: 25
          items:
            $ref: '#/components/schemas/LanguageTag'
          description: 'Languages to process when submitting an already-published version. Email templates accept submissions only for drafts, so setting this field for an email template is rejected.

            '
      example:
        expected_revision: 3
    TemplateSlug:
      type: string
      minLength: 1
      maxLength: 63
      pattern: ^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$
      description: 'A template''s slug: what you send it by, for example `welcome-email`. Email and SMS slugs stay fixed after creation. WhatsApp slugs can change only before the first submission. A slug can contain lowercase letters, numbers, hyphens, and underscores, has to start and end with a letter or a number, and can be up to 63 characters long.

        '
      example: welcome-email
  responses:
    Unprocessable:
      description: 'The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: 'The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

        '
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    RateLimit:
      description: 'Remaining capacity for the request''s rate-limit policy as an IETF Structured Field. Format: `"<policy>";r=<remaining>;t=<seconds_until_reset>`.

        '
      schema:
        type: string
      example: '"email_send";r=842;t=35'
    RetryAfter:
      description: 'Number of seconds to wait before retrying the request.

        '
      schema:
        type: integer
        minimum: 0
      example: 35
    RateLimit-Policy:
      description: 'Effective quota for the request''s rate-limit policy as an IETF Structured Field. Format: `"<policy>";q=<quota>;w=<window_seconds>`.

        '
      schema:
        type: string
      example: '"email_send";q=1000;w=60'
    IdempotencyReplay:
      description: The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.
      schema:
        type: string
        enum:
        - 'true'
  parameters:
    EndingBefore:
      name: ending_before
      in: query
      required: false
      description: Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.
      schema:
        type: string
    PaginationLimit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n  processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n  against a different request body or method. Generate a new key.\n\nRecommended key format is `<event-type>/<entity-id>` (for example `welcome-user/usr_abc123`).\n"
      schema:
        type: string
        maxLength: 255
    StartingAfter:
      name: starting_after
      in: query
      required: false
      description: Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Pass the API key as a bearer token in the `Authorization` header. Keys use

        the format `bk_{region}_*`. The prefix identifies the region and selects the

        API endpoint. Official Bird SDKs and the CLI derive the region from the key.

        '
    CookieAuth:
      type: apiKey
      in: cookie
      name: bird_session
      description: 'Session cookie set after signing in to the Bird dashboard. The cookie

        value is an opaque session token; no session data is stored in the cookie

        itself.

        '
    RealtimeKey:
      type: apiKey
      in: header
      name: X-Realtime-Key
      description: 'The Realtime app key. Together with `X-Realtime-Secret`, it authenticates a

        request to the Realtime API in addition to the workspace credential. Both

        values come from the app''s credentials and must belong to the calling

        workspace. Official Bird SDKs accept the pair as client configuration.

        '
    RealtimeSecret:
      type: apiKey
      in: header
      name: X-Realtime-Secret
      description: 'The Realtime app secret paired with `X-Realtime-Key`. The API returns the

        secret only when the key is created and does not store it. Create a new key

        and revoke the current key if you lose the secret. Official Bird SDKs accept

        the pair as client configuration.

        '