Hail Email Attachments API

openapi: 3.2.0
info:
  title: Hail Email Attachments API
  description: 'Give your AI agent a voice, a real phone number, and an inbox.


    This file is the source of truth for the Go CLI. Regenerate it after

    changing API routes — see docs/public/contributing.md.'
  version: 0.1.0
servers:
- url: https://api.hail.so
  description: Hail Cloud
tags:
- name: email-attachments
paths:
  /v1/email-attachments:
    post:
      tags:
      - email-attachments
      summary: Create Email Attachment
      description: 'Upload a file and get back a reusable attachment id.


        The returned id can be referenced from attachment_ids on many later

        POST /v1/emails calls until it is garbage-collected for being unused; it is

        not deleted immediately after first use. Uploads are size-limited and

        scoped to the caller''s organization.'
      operationId: upload_email_attachment
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_email_attachment'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAttachmentUploadResponse'
        '429':
          description: Rate limited. This caller exceeded the general request-rate ceiling. Retry after the Retry-After header (seconds).
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            RateLimit-Limit:
              description: The request ceiling for the current window.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema:
                type: integer
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_upload_email_attachment:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
          description: The file to upload, as multipart/form-data. Size-limited; an oversize upload is rejected with 422.
      type: object
      required:
      - file
      title: Body_upload_email_attachment
    EmailAttachmentUploadResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Reusable attachment id — pass it in EmailCreate.attachment_ids to attach it to a send.
        filename:
          type: string
          title: Filename
          description: Original filename of the uploaded file.
        content_type:
          type: string
          title: Content Type
          description: MIME type of the uploaded file.
        size_bytes:
          type: integer
          title: Size Bytes
          description: Size of the uploaded file in bytes.
      type: object
      required:
      - id
      - filename
      - content_type
      - size_bytes
      title: EmailAttachmentUploadResponse
      description: 'Returned by POST /email-attachments.


        ``id`` is reusable across many ``POST /emails`` calls via

        ``EmailCreate.attachment_ids`` until Hail garbage-collects it (24h

        if never referenced by a send).'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
          description: Path to the invalid field within the request, as a list of keys/indices (e.g. ['body', 'to']).
        msg:
          type: string
          title: Message
          description: Human-readable description of the validation failure.
        type:
          type: string
          title: Error Type
          description: Machine-readable error type code (e.g. 'missing', 'string_type').
        input:
          title: Input
          description: The value that was actually provided and failed validation.
        ctx:
          type: object
          title: Context
          description: Additional machine-readable context for the error, when the error type provides one.
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          description: 'List of validation errors: each entry gives the field location (loc), the problem (msg), and the error type (type).'
      type: object
      title: HTTPValidationError