AgentMail inboxes > files API

openapi: 3.2.0
info:
  title: Reference inboxes > files API
  version: 1.0.0
servers:
- url: https://api.agentmail.to
  description: prod
- url: https://x402.api.agentmail.to
  description: prod-x402
- url: https://mpp.api.agentmail.to
  description: prod-mpp
- url: https://api.agentmail.eu
  description: eu-prod
tags:
- name: inboxes > files
paths:
  /v0/inboxes/{inbox_id}/files:
    post:
      operationId: inboxes_files_create
      summary: Create File
      description: 'Starts an upload: creates a pending file at `path` and returns an `upload` to `PUT` its bytes to. The bytes go

        straight to storage, not through the API. Then call Complete File to make the file `ready`.


        Retry-safe: sending the identical request again (same `path`, `size`, `sha256`, `content_type` and

        `expires_at`) returns the existing file with `200` instead of `201`: a pending one with a fresh `upload`, or

        a `ready` one without. If its bytes were uploaded but the upload was never completed, it is completed then. A

        different request at a path whose file is still pending and has no bytes replaces that file; at any other

        taken path it returns `409`.


        The file counts against the organization''s Drive quota from creation, pending or not: 1 GiB and 10,000 files

        by default. A file that doesn''t fit returns `403` with code `limit_exceeded`. Deleting a file frees its

        space within seconds. Expired files count until a create needs their space: a create that doesn''t fit first

        gives back what expired files hold, a batch at a time, so retry a refusal while many expired files remain.


        Requires the `file_create` permission, which an unverified organization''s keys don''t have at any scope until

        it completes agent verification. A key without `file_read` can still create files, but gets the plain `409` at

        any taken path, even for an identical request at a file it didn''t create.


        Agent Drive is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet in EU

        production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.'
      tags:
      - inboxes > files
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files_CreateFileResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '403':
          description: '`code` says why: `forbidden` when the organization hasn''t joined AgentMail Labs; `missing_permission` when the

            credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn''t

            completed agent verification, and every file permission for an organization- or pod-scoped key under a

            content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or

            inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn''t fit the organization''s

            Drive quota.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  $ref: '#/components/schemas/files_FilePath'
                size:
                  $ref: '#/components/schemas/files_FileSize'
                sha256:
                  $ref: '#/components/schemas/files_FileSha256'
                content_type:
                  $ref: '#/components/schemas/files_FileContentType'
                expires_at:
                  $ref: '#/components/schemas/files_FileExpiresAt'
                  description: 'When the file expires, in the future. Rounded up to a whole second and returned in UTC. On a retry, send

                    the `expires_at` the first response returned.'
              required:
              - path
              - size
              - sha256
      security:
      - Bearer: []
    get:
      operationId: inboxes_files_list
      summary: List Files
      description: 'Lists the inbox''s files in path order, pending ones included, optionally only those whose path starts with

        `path_prefix`. A prefix matches characters, not whole segments: `reports/q` matches `reports/q3.pdf`. Items

        carry no download URL; get a file for one.


        The list is read in the region that serves the request, so a file created or deleted a moment ago may not

        show yet. Expired files never show.


        Requires the `file_read` permission.'
      tags:
      - inboxes > files
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - name: path_prefix
        in: query
        description: Only files whose path starts with this. Held to the path rules, except it may stop partway.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Page size, 100 by default and at most 500.
        required: false
        schema:
          $ref: '#/components/schemas/Limit'
      - name: page_token
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PageToken'
      - name: ascending
        in: query
        description: Path order, `true` by default. `false` lists in reverse.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files_ListFilesResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '403':
          description: '`code` says why: `forbidden` when the organization hasn''t joined AgentMail Labs; `missing_permission` when the

            credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn''t

            completed agent verification, and every file permission for an organization- or pod-scoped key under a

            content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or

            inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn''t fit the organization''s

            Drive quota.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
  /v0/inboxes/{inbox_id}/files/{file_id}/complete:
    post:
      operationId: inboxes_files_complete
      summary: Complete File
      description: 'Makes a pending file `ready` once its bytes are uploaded, and returns it, with its `download_url` if the key

        has `file_read`. Calling it on a file that is already `ready` returns the file.


        Returns `409` if the bytes haven''t been uploaded yet, or if what was uploaded doesn''t match the file''s `size`

        and `sha256`. Returns `404` for a file that has expired or was deleted, including a pending file not

        completed within a day of its creation.


        Requires the `file_create` permission. Only a key with `file_read`, or the key that created the file, can

        complete it; any other key gets `404`.'
      tags:
      - inboxes > files
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - name: file_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/files_FileId'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files_File'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '403':
          description: '`code` says why: `forbidden` when the organization hasn''t joined AgentMail Labs; `missing_permission` when the

            credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn''t

            completed agent verification, and every file permission for an organization- or pod-scoped key under a

            content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or

            inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn''t fit the organization''s

            Drive quota.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
  /v0/inboxes/{inbox_id}/files/{file_id}:
    get:
      operationId: inboxes_files_get
      summary: Get File
      description: 'Gets a file. A `ready` file comes with a fresh `download_url`, valid for up to an hour.


        A get reads the region that serves the request, so for about a second after a delete it can still return

        the deleted file. A file that has expired returns `404` at once.


        Requires the `file_read` permission.'
      tags:
      - inboxes > files
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - name: file_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/files_FileId'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files_File'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '403':
          description: '`code` says why: `forbidden` when the organization hasn''t joined AgentMail Labs; `missing_permission` when the

            credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn''t

            completed agent verification, and every file permission for an organization- or pod-scoped key under a

            content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or

            inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn''t fit the organization''s

            Drive quota.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
    delete:
      operationId: inboxes_files_delete
      summary: Delete File
      description: 'Deletes a file, pending or `ready`, and frees its path at once. Its bytes are deleted, and its space given

        back to the organization''s quota, within seconds. A download URL signed before the delete keeps working

        until it expires, at most an hour. Deleting a file that is already gone returns `404`.


        Requires the `file_delete` permission. Only a key with `file_read`, or the key that created the file, can

        delete it; any other key gets `404`.'
      tags:
      - inboxes > files
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/inboxes_InboxId'
      - name: file_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/files_FileId'
      responses:
        '200':
          description: Successful response
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '403':
          description: '`code` says why: `forbidden` when the organization hasn''t joined AgentMail Labs; `missing_permission` when the

            credential lacks the file permission the endpoint needs, including `file_create` in an organization that hasn''t

            completed agent verification, and every file permission for an organization- or pod-scoped key under a

            content-access policy; `account_suspended`, `pod_suspended` or `inbox_suspended` when the organization, pod or

            inbox is suspended; and, for Create File only, `limit_exceeded` when the file doesn''t fit the organization''s

            Drive quota.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - Bearer: []
components:
  schemas:
    files_FileSize:
      type: integer
      description: Size of the file in bytes. At most 104,857,600 (100 MiB).
      title: FileSize
    inboxes_Email:
      type: string
      description: Email address of the inbox.
      title: Email
    files_FileStatus:
      type: string
      enum:
      - pending
      - ready
      description: '`pending` until its bytes are uploaded and the upload is completed, then `ready`. Only a `ready` file has a

        download URL. A pending file is deleted if it isn''t completed within a day.'
      title: FileStatus
    files_FileId:
      type: string
      description: ID of the file. A UUID.
      title: FileId
    Count:
      type: integer
      description: Number of items returned.
      title: Count
    ErrorCode:
      type: string
      description: Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
      title: ErrorCode
    inboxes_InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    files_File:
      type: object
      properties:
        file_id:
          $ref: '#/components/schemas/files_FileId'
        inbox_id:
          $ref: '#/components/schemas/inboxes_InboxId'
        email:
          $ref: '#/components/schemas/inboxes_Email'
        path:
          $ref: '#/components/schemas/files_FilePath'
        name:
          $ref: '#/components/schemas/files_FileName'
        size:
          $ref: '#/components/schemas/files_FileSize'
        content_type:
          $ref: '#/components/schemas/files_FileContentType'
        sha256:
          $ref: '#/components/schemas/files_FileSha256'
        status:
          $ref: '#/components/schemas/files_FileStatus'
        created_at:
          type: string
          format: date-time
          description: When the file was created.
        updated_at:
          type: string
          format: date-time
          description: When the file last changed, such as when its upload was completed.
        expires_at:
          $ref: '#/components/schemas/files_FileExpiresAt'
        download_url:
          type: string
          description: 'A signed URL that downloads the file''s bytes, named by `name`. No API key is needed to use it, so treat it

            as a secret. It works until `download_expires_at`, at most an hour, even after the file is deleted. Get the

            file again for a fresh one.'
        download_expires_at:
          type: string
          format: date-time
          description: When `download_url` stops working. Never after the file's own expiry.
      required:
      - file_id
      - inbox_id
      - email
      - path
      - name
      - size
      - content_type
      - sha256
      - status
      - created_at
      - updated_at
      description: A file. A `ready` file returned to a caller with the `file_read` permission carries a signed `download_url`.
      title: File
    files_FileName:
      type: string
      description: The path's last segment. A download saves under this name.
      title: FileName
    files_FileSha256:
      type: string
      description: 'The base64 encoding of the file''s 32-byte SHA-256 digest, as S3''s `x-amz-checksum-sha256` takes it (44

        characters, ending in `=`). S3 refuses an upload whose bytes don''t match.'
      title: FileSha256
    files_FilePath:
      type: string
      description: 'Where the file lives in its inbox''s drive, such as `reports/q3.pdf`. Unique within the inbox. Segments are

        separated by `/`, with no leading or trailing `/`, no empty, `.` or `..` segment, no `\` and no control or

        invisible characters. At most 1,024 bytes, and at most 255 bytes per segment. Stored in Unicode NFC, so two

        spellings of one name are one path. Case is kept.'
      title: FilePath
    ErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ErrorName'
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          $ref: '#/components/schemas/ErrorMessage'
        fix:
          $ref: '#/components/schemas/ErrorFix'
        docs:
          $ref: '#/components/schemas/ErrorDocs'
      required:
      - name
      - message
      title: ErrorResponse
    files_FileExpiresAt:
      type: string
      format: date-time
      description: 'When the file expires. After it, the file is gone from get and list and its path is free; its bytes are

        deleted soon after. Absent for a file that never expires.'
      title: FileExpiresAt
    files_FileItem:
      type: object
      properties:
        file_id:
          $ref: '#/components/schemas/files_FileId'
        inbox_id:
          $ref: '#/components/schemas/inboxes_InboxId'
        email:
          $ref: '#/components/schemas/inboxes_Email'
        path:
          $ref: '#/components/schemas/files_FilePath'
        name:
          $ref: '#/components/schemas/files_FileName'
        size:
          $ref: '#/components/schemas/files_FileSize'
        content_type:
          $ref: '#/components/schemas/files_FileContentType'
        sha256:
          $ref: '#/components/schemas/files_FileSha256'
        status:
          $ref: '#/components/schemas/files_FileStatus'
        created_at:
          type: string
          format: date-time
          description: When the file was created.
        updated_at:
          type: string
          format: date-time
          description: When the file last changed, such as when its upload was completed.
        expires_at:
          $ref: '#/components/schemas/files_FileExpiresAt'
      required:
      - file_id
      - inbox_id
      - email
      - path
      - name
      - size
      - content_type
      - sha256
      - status
      - created_at
      - updated_at
      description: A file, as a list returns it.
      title: FileItem
    ErrorFix:
      type: string
      description: The concrete next action that resolves the error.
      title: ErrorFix
    PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    files_ListFilesResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/Count'
        limit:
          $ref: '#/components/schemas/Limit'
        next_page_token:
          $ref: '#/components/schemas/PageToken'
        files:
          type: array
          items:
            $ref: '#/components/schemas/files_FileItem'
          description: The inbox's files in path order. A list has no download URLs; get a file for one.
      required:
      - count
      - limit
      - files
      title: ListFilesResponse
    Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    ErrorMessage:
      type: string
      description: Error message.
      title: ErrorMessage
    files_CreateFileResponse:
      type: object
      properties:
        file_id:
          $ref: '#/components/schemas/files_FileId'
        inbox_id:
          $ref: '#/components/schemas/inboxes_InboxId'
        email:
          $ref: '#/components/schemas/inboxes_Email'
        path:
          $ref: '#/components/schemas/files_FilePath'
        name:
          $ref: '#/components/schemas/files_FileName'
        size:
          $ref: '#/components/schemas/files_FileSize'
        content_type:
          $ref: '#/components/schemas/files_FileContentType'
        sha256:
          $ref: '#/components/schemas/files_FileSha256'
        status:
          $ref: '#/components/schemas/files_FileStatus'
        created_at:
          type: string
          format: date-time
          description: When the file was created.
        updated_at:
          type: string
          format: date-time
          description: When the file last changed, such as when its upload was completed.
        expires_at:
          $ref: '#/components/schemas/files_FileExpiresAt'
        download_url:
          type: string
          description: 'A signed URL that downloads the file''s bytes, named by `name`. No API key is needed to use it, so treat it

            as a secret. It works until `download_expires_at`, at most an hour, even after the file is deleted. Get the

            file again for a fresh one.'
        download_expires_at:
          type: string
          format: date-time
          description: When `download_url` stops working. Never after the file's own expiry.
        upload:
          $ref: '#/components/schemas/files_FileUpload'
      required:
      - file_id
      - inbox_id
      - email
      - path
      - name
      - size
      - content_type
      - sha256
      - status
      - created_at
      - updated_at
      description: The created file. A pending file carries `upload`; a create that returns an existing `ready` file does not.
      title: CreateFileResponse
    ErrorDocs:
      type: string
      description: Link to the error reference entry for this code.
      title: ErrorDocs
    ErrorName:
      type: string
      description: Name of error.
      title: ErrorName
    ValidationErrorResponse:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ErrorName'
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          $ref: '#/components/schemas/ErrorMessage'
        errors:
          description: Validation errors. Each entry has a path and a message identifying the invalid field.
        fix:
          $ref: '#/components/schemas/ErrorFix'
        docs:
          $ref: '#/components/schemas/ErrorDocs'
      required:
      - name
      - errors
      title: ValidationErrorResponse
    files_FileUpload:
      type: object
      properties:
        method:
          type: string
          enum:
          - PUT
          description: Always `PUT`.
        url:
          type: string
          description: The presigned S3 URL. No API key is needed to use it.
        headers:
          type: object
          additionalProperties:
            type: string
          description: The headers to send with the `PUT`, exactly as given.
        expires_at:
          type: string
          format: date-time
          description: When `url` stops working, at most an hour after it was issued. Send the identical create request again for a fresh one.
      required:
      - method
      - url
      - headers
      - expires_at
      description: 'Where to upload a pending file''s bytes: one HTTP `PUT` to `url` with exactly `headers` and the file''s bytes as

        the body. Every header is signed, so S3 refuses the upload if any is missing or different, and refuses bytes

        whose size or SHA-256 doesn''t match the file. Then call Complete File.'
      title: FileUpload
    files_FileContentType:
      type: string
      description: The file's MIME type, such as `application/pdf`. Defaults to `application/octet-stream`.
      title: FileContentType
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer