openapi: 3.1.0
info:
  title: SendHQ API
  version: '2026-08-23'
  description: Send and receive expected email, manage verified domains and hosted templates, and inspect
    delivery outcomes.
servers:
- url: https://sendhq.cc/api/v1
tags:
- name: Emails and threads
  description: Send, retrieve, search, reply, and inspect delivery events.
- name: Drafts and attachments
  description: Build composer flows with private attachment storage.
- name: Hosted templates
  description: Draft, render, test, version, publish, and send reusable content.
- name: Domains
  description: Provision sender identities and understand DNS verification state.
- name: Inbound email
  description: Create addresses and work with received conversations.
- name: Deliverability
  description: Inspect events, reputation outcomes, and blocked recipients.
- name: Account and billing
  description: Session-authenticated workspace administration.
paths:
  /emails:
    post:
      operationId: post_emails
      tags:
      - Emails and threads
      summary: Send one email
      description: Send transactional HTML, text, or hosted-template content from a verified workspace
        domain.
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  providerMessageId:
                    type: string
                  threadId:
                    type: string
                required:
                - id
                - providerMessageId
                - threadId
                additionalProperties: false
              example:
                id: em_…
                providerMessageId: provider-id
                threadId: em_…
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                to:
                  type: array
                  items:
                    type: string
                    format: email
                subject:
                  type: string
                html:
                  type: string
                text:
                  type: string
              required:
              - from
              - to
              - subject
              - html
              - text
              additionalProperties: false
            example:
              from: Acme <hello@example.com>
              to:
              - customer@example.net
              subject: Welcome aboard
              html: <h1>Welcome</h1><p>Your workspace is ready.</p>
              text: Welcome. Your workspace is ready.
    get:
      operationId: get_emails
      tags:
      - Emails and threads
      summary: List sent and received email
      description: List sent and received email
      security:
      - bearerAuth: []
      parameters:
      - name: direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - in
          - out
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: domain
        in: query
        required: false
        schema:
          type: string
      - name: inbox_id
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
      - name: to
        in: query
        required: false
        schema:
          type: string
      - name: unread
        in: query
        required: false
        schema:
          type: boolean
      - name: after
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: before
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: query
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /emails/batch:
    post:
      operationId: post_emails_batch
      tags:
      - Emails and threads
      summary: Send up to 100 individualized messages
      description: Send up to 100 individualized messages
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        ok:
                          type: boolean
                        id:
                          type: string
                      required:
                      - index
                      - ok
                      - id
                      additionalProperties: false
                  count:
                    type: integer
                  successful:
                    type: integer
                  failed:
                    type: integer
                required:
                - data
                - count
                - successful
                - failed
                additionalProperties: false
              example:
                data:
                - index: 0
                  ok: true
                  id: em_…
                count: 1
                successful: 1
                failed: 0
        '207':
          description: Successful response with partial outcomes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        ok:
                          type: boolean
                        id:
                          type: string
                      required:
                      - index
                      - ok
                      - id
                      additionalProperties: false
                  count:
                    type: integer
                  successful:
                    type: integer
                  failed:
                    type: integer
                required:
                - data
                - count
                - successful
                - failed
                additionalProperties: false
              example:
                data:
                - index: 0
                  ok: true
                  id: em_…
                count: 1
                successful: 1
                failed: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  items:
                    type: object
                    properties:
                      from:
                        type: string
                      to:
                        type: array
                        items:
                          type: string
                          format: email
                      subject:
                        type: string
                      html:
                        type: string
                      text:
                        type: string
                    required:
                    - from
                    - to
                    - subject
                    - html
                    - text
                    additionalProperties: false
              required:
              - emails
              additionalProperties: false
            example:
              emails:
              - from: Acme <hello@example.com>
                to:
                - customer@example.net
                subject: Welcome aboard
                html: <h1>Welcome</h1><p>Your workspace is ready.</p>
                text: Welcome. Your workspace is ready.
  /emails/{id}:
    get:
      operationId: get_emails_id
      tags:
      - Emails and threads
      summary: Retrieve an email and its attachments
      description: Retrieve an email and its attachments
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  direction:
                    type: string
                  status:
                    type: string
                  attachments:
                    type: array
                    items: {}
                required:
                - id
                - direction
                - status
                - attachments
                additionalProperties: false
              example:
                id: em_…
                direction: out
                status: sent
                attachments: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      operationId: patch_emails_id
      tags:
      - Emails and threads
      summary: Mark an email read or unread
      description: Mark an email read or unread
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  readAt:
                    type: string
                    format: date-time
                required:
                - id
                - readAt
                additionalProperties: false
              example:
                id: em_…
                readAt: '2026-08-23T12:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                read:
                  type: boolean
              required:
              - read
              additionalProperties: false
            example:
              read: true
    delete:
      operationId: delete_emails_id
      tags:
      - Emails and threads
      summary: Delete a retained email
      description: Delete a retained email
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /emails/{id}/events:
    get:
      operationId: get_emails_id_events
      tags:
      - Emails and threads
      summary: List delivery events for an email
      description: List delivery events for an email
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /threads/{id}:
    get:
      operationId: get_threads_id
      tags:
      - Emails and threads
      summary: Retrieve a conversation chronologically
      description: Retrieve a conversation chronologically
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - id
                - data
                - count
                additionalProperties: false
              example:
                id: em_…
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /drafts:
    post:
      operationId: post_drafts
      tags:
      - Drafts and attachments
      summary: Create a composer draft
      description: Create a composer draft
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  attachments:
                    type: array
                    items: {}
                required:
                - id
                - attachments
                additionalProperties: false
              example:
                id: dr_…
                attachments: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  format: email
                to:
                  type: array
                  items:
                    type: string
                    format: email
                subject:
                  type: string
              required:
              - from
              - to
              - subject
              additionalProperties: false
            example:
              from: hello@example.com
              to:
              - customer@example.net
              subject: Hello
    get:
      operationId: get_drafts
      tags:
      - Drafts and attachments
      summary: List composer drafts
      description: List composer drafts
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /drafts/{id}:
    get:
      operationId: get_drafts_id
      tags:
      - Drafts and attachments
      summary: Retrieve a draft and attachments
      description: Retrieve a draft and attachments
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  attachments:
                    type: array
                    items: {}
                required:
                - id
                - attachments
                additionalProperties: false
              example:
                id: dr_…
                attachments: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    put:
      operationId: put_drafts_id
      tags:
      - Drafts and attachments
      summary: Replace draft content
      description: Replace draft content
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                required:
                - id
                additionalProperties: false
              example:
                id: dr_…
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  format: email
                to:
                  type: array
                  items:
                    type: string
                    format: email
                subject:
                  type: string
                text:
                  type: string
              required:
              - from
              - to
              - subject
              - text
              additionalProperties: false
            example:
              from: hello@example.com
              to:
              - customer@example.net
              subject: Updated subject
              text: Updated body
    delete:
      operationId: delete_drafts_id
      tags:
      - Drafts and attachments
      summary: Discard a draft
      description: Discard a draft
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /drafts/{id}/attachments:
    post:
      operationId: post_drafts_id_attachments
      tags:
      - Drafts and attachments
      summary: Upload an attachment to a draft
      description: Upload raw file bytes. Set Content-Type and X-Filename. A message can contain at most
        10 files and 10 MB total.
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: X-Filename
        in: header
        required: false
        schema:
          type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  filename:
                    type: string
                  sizeBytes:
                    type: integer
                  available:
                    type: boolean
                required:
                - id
                - filename
                - sizeBytes
                - available
                additionalProperties: false
              example:
                id: att_…
                filename: invoice.pdf
                sizeBytes: 48231
                available: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /attachments/{id}:
    get:
      operationId: get_attachments_id
      tags:
      - Drafts and attachments
      summary: Download a private attachment
      description: Download a private attachment
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/octet-stream:
              schema:
                type: string
                contentEncoding: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: delete_attachments_id
      tags:
      - Drafts and attachments
      summary: Delete a private attachment
      description: Delete a private attachment
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /sending-identities:
    get:
      operationId: get_sending_identities
      tags:
      - Drafts and attachments
      summary: List verified sender identities
      description: List verified sender identities
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  domains:
                    type: array
                    items: {}
                  addresses:
                    type: array
                    items: {}
                  localParts:
                    type: array
                    items: {}
                required:
                - domains
                - addresses
                - localParts
                additionalProperties: false
              example:
                domains: []
                addresses: []
                localParts: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /templates:
    get:
      operationId: get_templates
      tags:
      - Hosted templates
      summary: List hosted templates
      description: List hosted templates
      security:
      - bearerAuth: []
      parameters:
      - name: lifecycle
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - archived
          - all
      - name: query
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: post_templates
      tags:
      - Hosted templates
      summary: Create a hosted template
      description: Create a hosted template
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    type: object
                    properties:
                      id:
                        type: string
                      key:
                        type: string
                    required:
                    - id
                    - key
                    additionalProperties: false
                required:
                - template
                additionalProperties: false
              example:
                template:
                  id: tmpl_…
                  key: account-welcome
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                key:
                  type: string
                starter:
                  type: string
              required:
              - name
              - key
              - starter
              additionalProperties: false
            example:
              name: Account welcome
              key: account-welcome
              starter: welcome
  /templates/{id}:
    get:
      operationId: get_templates_id
      tags:
      - Hosted templates
      summary: Retrieve drafts, releases, and usage
      description: Retrieve drafts, releases, and usage
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    type: object
                    properties:
                      id:
                        type: string
                    required:
                    - id
                    additionalProperties: false
                  versions:
                    type: array
                    items: {}
                  draft: {}
                  activeVersion: {}
                  usage:
                    type: array
                    items: {}
                required:
                - template
                - versions
                - draft
                - activeVersion
                - usage
                additionalProperties: false
              example:
                template:
                  id: tmpl_…
                versions: []
                draft: null
                activeVersion: null
                usage: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /templates/{id}/draft:
    put:
      operationId: put_templates_id_draft
      tags:
      - Hosted templates
      summary: Autosave a template draft
      description: Autosave a template draft
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  draft:
                    type: object
                    properties:
                      id:
                        type: string
                      revision:
                        type: integer
                    required:
                    - id
                    - revision
                    additionalProperties: false
                required:
                - draft
                additionalProperties: false
              example:
                draft:
                  id: tmplv_…
                  revision: 2
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                revision:
                  type: integer
                name:
                  type: string
                subjectTemplate:
                  type: string
                htmlTemplate:
                  type: string
                textTemplate:
                  type: string
                variables:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      type:
                        type: string
                      required:
                        type: boolean
                    required:
                    - key
                    - type
                    - required
                    additionalProperties: false
                sampleData:
                  type: object
                  properties:
                    first_name:
                      type: string
                  required:
                  - first_name
                  additionalProperties: false
              required:
              - revision
              - name
              - subjectTemplate
              - htmlTemplate
              - textTemplate
              - variables
              - sampleData
              additionalProperties: false
            example:
              revision: 1
              name: Account welcome
              subjectTemplate: Welcome, {{first_name}}
              htmlTemplate: <h1>Welcome, {{first_name}}</h1>
              textTemplate: Welcome, {{first_name}}
              variables:
              - key: first_name
                type: string
                required: true
              sampleData:
                first_name: Asha
    post:
      operationId: post_templates_id_draft
      tags:
      - Hosted templates
      summary: Create a new draft from the published release
      description: Create a new draft from the published release
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  draft:
                    type: object
                    properties:
                      id:
                        type: string
                      revision:
                        type: integer
                    required:
                    - id
                    - revision
                    additionalProperties: false
                required:
                - draft
                additionalProperties: false
              example:
                draft:
                  id: tmplv_…
                  revision: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /templates/{id}/render:
    post:
      operationId: post_templates_id_render
      tags:
      - Hosted templates
      summary: Render exact server output
      description: Render exact server output
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  subject:
                    type: string
                  html:
                    type: string
                  text:
                    type: string
                  findings:
                    type: array
                    items: {}
                required:
                - subject
                - html
                - text
                - findings
                additionalProperties: false
              example:
                subject: Welcome, Asha
                html: <h1>Welcome, Asha</h1>
                text: Welcome, Asha
                findings: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    first_name:
                      type: string
                  required:
                  - first_name
                  additionalProperties: false
              required:
              - data
              additionalProperties: false
            example:
              data:
                first_name: Asha
  /templates/{id}/test:
    post:
      operationId: post_templates_id_test
      tags:
      - Hosted templates
      summary: Send a test snapshot
      description: Send a test snapshot
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  isTest:
                    type: boolean
                required:
                - id
                - isTest
                additionalProperties: false
              example:
                id: em_…
                isTest: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to:
                  type: array
                  items:
                    type: string
                    format: email
                from:
                  type: string
                  format: email
                data:
                  type: object
                  properties:
                    first_name:
                      type: string
                  required:
                  - first_name
                  additionalProperties: false
              required:
              - to
              - from
              - data
              additionalProperties: false
            example:
              to:
              - owner@example.com
              from: hello@example.com
              data:
                first_name: Asha
  /templates/{id}/publish:
    post:
      operationId: post_templates_id_publish
      tags:
      - Hosted templates
      summary: Publish an immutable template release
      description: Publish an immutable template release
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: object
                    properties:
                      id:
                        type: string
                      state:
                        type: string
                    required:
                    - id
                    - state
                    additionalProperties: false
                required:
                - version
                additionalProperties: false
              example:
                version:
                  id: tmplv_…
                  state: published
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /templates/{id}/archive:
    post:
      operationId: post_templates_id_archive
      tags:
      - Hosted templates
      summary: Archive a template
      description: Archive a template
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    type: object
                    properties:
                      id:
                        type: string
                      lifecycle:
                        type: string
                    required:
                    - id
                    - lifecycle
                    additionalProperties: false
                required:
                - template
                additionalProperties: false
              example:
                template:
                  id: tmpl_…
                  lifecycle: archived
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /templates/{id}/restore:
    post:
      operationId: post_templates_id_restore
      tags:
      - Hosted templates
      summary: Restore an archived template
      description: Restore an archived template
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    type: object
                    properties:
                      id:
                        type: string
                      lifecycle:
                        type: string
                    required:
                    - id
                    - lifecycle
                    additionalProperties: false
                required:
                - template
                additionalProperties: false
              example:
                template:
                  id: tmpl_…
                  lifecycle: active
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /domains:
    post:
      operationId: post_domains
      tags:
      - Domains
      summary: Add a sending domain
      description: Add a sending domain
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  status:
                    type: string
                  records:
                    type: array
                    items: {}
                required:
                - id
                - name
                - status
                - records
                additionalProperties: false
              example:
                id: dom_…
                name: example.com
                status: pending
                records: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
              - name
              additionalProperties: false
            example:
              name: example.com
    get:
      operationId: get_domains
      tags:
      - Domains
      summary: List domains and cached DNS state
      description: List domains and cached DNS state
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /domains/{id}:
    get:
      operationId: get_domains_id
      tags:
      - Domains
      summary: Retrieve domain setup details
      description: Retrieve domain setup details
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  setup_status:
                    type: string
                  records:
                    type: array
                    items: {}
                  dns_issues:
                    type: array
                    items: {}
                required:
                - id
                - name
                - setup_status
                - records
                - dns_issues
                additionalProperties: false
              example:
                id: dom_…
                name: example.com
                setup_status: checking
                records: []
                dns_issues: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: delete_domains_id
      tags:
      - Domains
      summary: Delete a domain
      description: Delete a domain
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /domains/{id}/verify:
    post:
      operationId: post_domains_id_verify
      tags:
      - Domains
      summary: Refresh SES and DNS verification
      description: Refresh SES and DNS verification
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: object
                    properties:
                      id:
                        type: string
                      status:
                        type: string
                    required:
                    - id
                    - status
                    additionalProperties: false
                  checks:
                    type: object
                    properties:
                      ses:
                        type: boolean
                    required:
                    - ses
                    additionalProperties: false
                  status:
                    type: string
                required:
                - domain
                - checks
                - status
                additionalProperties: false
              example:
                domain:
                  id: dom_…
                  status: verified
                checks:
                  ses: true
                status: verified
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /inboxes:
    post:
      operationId: post_inboxes
      tags:
      - Inbound email
      summary: Create an inbound address
      description: Create an inbound address
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  address:
                    type: string
                    format: email
                  status:
                    type: string
                required:
                - id
                - address
                - status
                additionalProperties: false
              example:
                id: inb_…
                address: support@inbound.example.com
                status: active
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domain_id:
                  type: string
                local_part:
                  type: string
                name:
                  type: string
              required:
              - domain_id
              - local_part
              - name
              additionalProperties: false
            example:
              domain_id: dom_…
              local_part: support
              name: Support
    get:
      operationId: get_inboxes
      tags:
      - Inbound email
      summary: List inbound addresses
      description: List inbound addresses
      security:
      - bearerAuth: []
      parameters:
      - name: domain_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /inboxes/{id}:
    get:
      operationId: get_inboxes_id
      tags:
      - Inbound email
      summary: Retrieve an inbound address
      description: Retrieve an inbound address
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  address:
                    type: string
                    format: email
                  status:
                    type: string
                required:
                - id
                - address
                - status
                additionalProperties: false
              example:
                id: inb_…
                address: support@example.com
                status: active
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      operationId: patch_inboxes_id
      tags:
      - Inbound email
      summary: Rename, enable, or disable an inbox
      description: Rename, enable, or disable an inbox
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                required:
                - id
                - status
                additionalProperties: false
              example:
                id: inb_…
                status: active
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                status:
                  type: string
              required:
              - name
              - status
              additionalProperties: false
            example:
              name: Customer support
              status: active
    delete:
      operationId: delete_inboxes_id
      tags:
      - Inbound email
      summary: Delete an inbox while retaining messages
      description: Delete an inbox while retaining messages
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /deliverability/stats:
    get:
      operationId: get_deliverability_stats
      tags:
      - Deliverability
      summary: Retrieve 30-day delivery statistics
      description: Retrieve 30-day delivery statistics
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  window:
                    type: string
                  sent:
                    type: integer
                  delivery:
                    type: integer
                  bounce:
                    type: integer
                  complaint:
                    type: integer
                  deliveryRate: {}
                required:
                - window
                - sent
                - delivery
                - bounce
                - complaint
                - deliveryRate
                additionalProperties: false
              example:
                window: 30d
                sent: 0
                delivery: 0
                bounce: 0
                complaint: 0
                deliveryRate: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /suppressions:
    get:
      operationId: get_suppressions
      tags:
      - Deliverability
      summary: List workspace suppressions
      description: List workspace suppressions
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /suppressions/{email}:
    delete:
      operationId: delete_suppressions_email
      tags:
      - Deliverability
      summary: Remove an eligible bounce suppression
      description: Remove an eligible bounce suppression
      security:
      - bearerAuth: []
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /blocked-recipients:
    get:
      operationId: get_blocked_recipients
      tags:
      - Deliverability
      summary: List bounces, complaints, and unsubscribes
      description: List bounces, complaints, and unsubscribes
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                      unsubscribe:
                        type: integer
                      bounce:
                        type: integer
                      complaint:
                        type: integer
                    required:
                    - total
                    - unsubscribe
                    - bounce
                    - complaint
                    additionalProperties: false
                required:
                - data
                - count
                - summary
                additionalProperties: false
              example:
                data: []
                count: 0
                summary:
                  total: 0
                  unsubscribe: 0
                  bounce: 0
                  complaint: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /profile:
    get:
      operationId: get_profile
      tags:
      - Account and billing
      summary: Retrieve account, usage, and subscription state
      description: Retrieve account, usage, and subscription state
      security:
      - sessionCookie: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties: false
                  usage:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties: false
                  access:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties: false
                  reputation:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties: false
                  billing:
                    type: object
                    properties: {}
                    required: []
                    additionalProperties: false
                  plans:
                    type: array
                    items: {}
                required:
                - user
                - usage
                - access
                - reputation
                - billing
                - plans
                additionalProperties: false
              example:
                user: {}
                usage: {}
                access: {}
                reputation: {}
                billing: {}
                plans: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /billing/checkout:
    post:
      operationId: post_billing_checkout
      tags:
      - Account and billing
      summary: Create a hosted checkout session
      description: Create a hosted checkout session
      security:
      - sessionCookie: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  session_id:
                    type: string
                required:
                - url
                - session_id
                additionalProperties: false
              example:
                url: https://checkout.example/…
                session_id: …
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan_key:
                  type: string
              required:
              - plan_key
              additionalProperties: false
            example:
              plan_key: indie_hackers
  /billing/portal:
    post:
      operationId: post_billing_portal
      tags:
      - Account and billing
      summary: Create a billing portal session
      description: Create a billing portal session
      security:
      - sessionCookie: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                required:
                - url
                additionalProperties: false
              example:
                url: https://billing.example/…
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /keys:
    post:
      operationId: post_keys
      tags:
      - Account and billing
      summary: Create an API key
      description: Create an API key
      security:
      - sessionCookie: []
      parameters: []
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  key:
                    type: string
                  prefix:
                    type: string
                required:
                - id
                - name
                - key
                - prefix
                additionalProperties: false
              example:
                id: key_…
                name: Production
                key: re_…
                prefix: re_…
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
              - name
              additionalProperties: false
            example:
              name: Production
    get:
      operationId: get_keys
      tags:
      - Account and billing
      summary: List API-key metadata
      description: List API-key metadata
      security:
      - sessionCookie: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                  count:
                    type: integer
                required:
                - data
                - count
                additionalProperties: false
              example:
                data: []
                count: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /keys/{id}:
    delete:
      operationId: delete_keys_id
      tags:
      - Account and billing
      summary: Revoke an API key
      description: Revoke an API key
      security:
      - sessionCookie: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
                additionalProperties: false
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: re_…
      description: Workspace API key. Keep it server-side.
    sessionCookie:
      type: apiKey
      in: cookie
      name: sendhq_session_v2
      description: Browser session used for account administration.
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - status
          properties:
            message:
              type: string
            status:
              type: integer
            code:
              type:
              - string
              - 'null'
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: A usage or reputation limit was reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'