Cherami Labels API

openapi: 3.2.0
info:
  title: Cherami To Labels API
  version: 1.0.0
  contact:
    name: Cherami
    email: hello@cherami.to
  description: 'Operations tagged labels across 2 of this provider''s published API definitions: cherami-to-openapi.json, cherami-to-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://cherami.to
security:
- apiKey: []
tags:
- name: Labels
paths:
  /v1/messages/{message_id}:
    patch:
      operationId: updateMessageLabels
      tags:
      - Labels
      summary: Label a received message
      description: 'Adds and removes labels on one received message, leaving its other labels as they are. Names are case-sensitive: `Receipts` and `receipts` are different labels. The response lists the message''s labels after the change, and repeating a change is harmless.


        To track read and starred mail with labels, see Track read, unread and starred mail.'
      parameters:
      - name: message_id
        in: path
        required: true
        schema:
          type: string
        description: Cherami resource ID returned by the API.
      responses:
        '200':
          description: Success.
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResult'
              example:
                id: 11111111-1111-4111-8111-111111111111
                labels: []
        '400':
          description: '`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.


            `invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '`body_too_large`: Reduce the JSON request to the operation''s body limit.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: '`unsupported_media_type`: Send `Content-Type: application/json`.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-error-codes:
      - unauthorized
      - invalid_json
      - body_too_large
      - unsupported_media_type
      - not_found
      - invalid_labels
      - internal_error
      requestBody:
        required: true
        description: JSON object, at most 20 KiB in total.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelChange'
            example:
              add_labels:
              - handled
              remove_labels:
              - needs-review
      x-request-body-limit: 20480
      x-example-body:
        add_labels:
        - handled
        remove_labels:
        - needs-review
    servers:
    - url: https://cherami.to
  /v1/sent/{message_id}:
    patch:
      operationId: updateSentMessageLabels
      tags:
      - Labels
      summary: Label a sent copy
      description: Adds and removes labels on one sent copy, with the same rules as labelling a received message.
      parameters:
      - name: message_id
        in: path
        required: true
        schema:
          type: string
        description: Cherami resource ID returned by the API.
      responses:
        '200':
          description: Success.
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResult'
              example:
                id: 11111111-1111-4111-8111-111111111111
                labels: []
        '400':
          description: '`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.


            `invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '`body_too_large`: Reduce the JSON request to the operation''s body limit.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: '`unsupported_media_type`: Send `Content-Type: application/json`.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-error-codes:
      - unauthorized
      - invalid_json
      - body_too_large
      - unsupported_media_type
      - not_found
      - invalid_labels
      - internal_error
      requestBody:
        required: true
        description: JSON object, at most 20 KiB in total.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelChange'
            example:
              add_labels:
              - handled
              remove_labels:
              - needs-review
      x-request-body-limit: 20480
      x-example-body:
        add_labels:
        - handled
        remove_labels:
        - needs-review
    servers:
    - url: https://cherami.to
  /v1/messages/labels:
    patch:
      operationId: bulkUpdateMessageLabels
      tags:
      - Labels
      summary: Label several received messages
      description: 'Applies one label change to up to 100 received messages, which may be in any of the account''s inboxes. The label rules apply; sent copies have their own endpoint.


        The change is all or nothing: if any ID is missing, deleted or not on this account, the request returns `404` and no message changes. On success the response has one entry per distinct ID, in request order. For more than 100 messages, send several requests.'
      parameters: []
      responses:
        '200':
          description: Success.
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/LabelResult'
                required:
                - messages
              example:
                messages: []
        '400':
          description: '`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.


            `invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.


            `invalid_message_ids`: Supply 1–100 valid message IDs for a bulk label update.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '`body_too_large`: Reduce the JSON request to the operation''s body limit.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: '`unsupported_media_type`: Send `Content-Type: application/json`.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-error-codes:
      - unauthorized
      - invalid_json
      - body_too_large
      - unsupported_media_type
      - not_found
      - invalid_labels
      - invalid_message_ids
      - internal_error
      requestBody:
        required: true
        description: JSON object, at most 32 KiB in total.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkLabelChange'
            example:
              message_ids:
              - 22222222-2222-4222-8222-222222222222
              add_labels:
              - handled
      x-request-body-limit: 32768
      x-example-body:
        message_ids:
        - 22222222-2222-4222-8222-222222222222
        add_labels:
        - handled
    servers:
    - url: https://cherami.to
  /v1/sent/labels:
    patch:
      operationId: bulkUpdateSentLabels
      tags:
      - Labels
      summary: Label several sent copies
      description: 'Applies one label change to up to 100 sent copies, which may be in any of the account''s inboxes. The label rules apply; received messages have their own endpoint.


        The change is all or nothing: if any ID is missing, deleted or not on this account, the request returns `404` and no copy changes. On success the response has one entry per distinct ID, in request order. For more than 100 copies, send several requests.'
      parameters: []
      responses:
        '200':
          description: Success.
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/LabelResult'
                required:
                - messages
              example:
                messages: []
        '400':
          description: '`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.


            `invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.


            `invalid_message_ids`: Supply 1–100 valid message IDs for a bulk label update.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '`body_too_large`: Reduce the JSON request to the operation''s body limit.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: '`unsupported_media_type`: Send `Content-Type: application/json`.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-error-codes:
      - unauthorized
      - invalid_json
      - body_too_large
      - unsupported_media_type
      - not_found
      - invalid_labels
      - invalid_message_ids
      - internal_error
      requestBody:
        required: true
        description: JSON object, at most 32 KiB in total.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkLabelChange'
            example:
              message_ids:
              - 22222222-2222-4222-8222-222222222222
              add_labels:
              - handled
      x-request-body-limit: 32768
      x-example-body:
        message_ids:
        - 22222222-2222-4222-8222-222222222222
        add_labels:
        - handled
    servers:
    - url: https://cherami.to
  /v1/inboxes/{inbox_id}/labels:
    get:
      operationId: listLabels
      tags:
      - Labels
      summary: Discover labels
      description: 'Lists the label names in use on the inbox''s received and sent mail, with how many messages carry each in `received_count` and `sent_count`. `prefix` narrows the list to names starting with it, case-sensitive.


        A name disappears once no message carries it. There is no separate step to create, rename or delete a label: add or remove it on messages.'
      parameters:
      - name: inbox_id
        in: path
        required: true
        schema:
          type: string
        description: Cherami resource ID returned by the API.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Results per page.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: next_cursor from the previous page. Keep the URL, filters and order unchanged.
      - name: prefix
        in: query
        required: false
        schema:
          type: string
        description: Only names starting with this text, case-sensitive; empty means all. At most 128 UTF-8 bytes, supplied once.
      responses:
        '200':
          description: Success.
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelList'
              example:
                labels: []
                next_cursor: null
        '400':
          description: '`invalid_limit`: Use an integer from 1 to 100.


            `invalid_cursor`: Send a cursor only to the listing, filters and order that returned it, or restart from the first page.


            `invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.'
          headers:
            X-Request-ID:
              description: Identifies this request; include it when reporting a problem.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-error-codes:
      - unauthorized
      - not_found
      - invalid_limit
      - invalid_cursor
      - invalid_labels
      - internal_error
    servers:
    - url: https://cherami.to
components:
  schemas:
    LabelList:
      type: object
      properties:
        labels:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              received_count:
                type: integer
                minimum: 0
              sent_count:
                type: integer
                minimum: 0
            required:
            - name
            - received_count
            - sent_count
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - labels
      - next_cursor
    LabelChange:
      type: object
      properties:
        add_labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          maxItems: 32
          description: Label names, case-sensitive; order and duplicates don't matter.
        remove_labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          maxItems: 32
          description: Label names, case-sensitive; order and duplicates don't matter.
      required: []
      additionalProperties: false
      description: At least one array must contain a label, and a name can't be in both.
    BulkLabelChange:
      type: object
      properties:
        message_ids:
          type: array
          items:
            type: string
            description: Message ID, in lowercase.
            pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
          minItems: 1
          maxItems: 100
        add_labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          maxItems: 32
          description: Label names, case-sensitive; order and duplicates don't matter.
        remove_labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          maxItems: 32
          description: Label names, case-sensitive; order and duplicates don't matter.
      required:
      - message_ids
      additionalProperties: false
      description: At least one nonempty change array, and no name in both. Duplicate IDs are updated once.
    LabelResult:
      type: object
      properties:
        id:
          type: string
          description: Cherami resource ID.
        labels:
          type: array
          items:
            type: string
      required:
      - id
      - labels
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Code to handle. Handle a code you don't recognize by its HTTP status.
            message:
              type: string
              description: Explanation of this case; its wording can change.
          required:
          - code
          - message
      required:
      - error
    Label:
      type: string
      description: 1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.
      x-max-utf8-bytes: 128
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: Cherami API key
      description: Cherami API key (ch_...), from Account → API keys or from redeeming a human-approved phrase. Every key reaches all of the account's inboxes and mail. MCP OAuth tokens and browser sessions are not accepted.
x-refined-from:
- cherami-to-openapi.json
- cherami-to-openapi.yml