find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/openmail-sh:openmail-sh-pods-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: OpenMail Pods API
  description: Email infrastructure API for AI agents. Create inboxes, send and receive email, and get real-time notifications via webhooks.
  version: 1.0.0
  license:
    name: Proprietary
servers:
- url: https://api.openmail.sh
security:
- bearerAuth: []
tags:
- name: Pods
  description: Isolated sub-accounts for your end users or tenants
paths:
  /v1/pods:
    post:
      operationId: createPod
      summary: Create pod
      tags:
      - Pods
      description: Create a new pod (an isolated sub-account for one of your end users or tenants). Pass your own `clientId` to map the pod to a record in your system and address it later without storing the OpenMail ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                clientId:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  description: Your own stable identifier for this pod (e.g. your user/tenant ID). Must be unique within your account. Use it in place of the pod ID on any pod or inbox endpoint.
                name:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  description: Human-readable label shown in the console.
      responses:
        '201':
          description: Pod created
          content:
            application/json:
              schema:
                description: Pod created
                allOf:
                - $ref: '#/components/schemas/Pod'
        '409':
          description: A pod with the same `clientId` already exists in your account
          content:
            application/json:
              schema:
                description: A pod with the same `clientId` already exists in your account
                allOf:
                - $ref: '#/components/schemas/Error'
    get:
      operationId: listPods
      summary: List pods
      tags:
      - Pods
      description: List all pods for your account. The default pod is always returned first. Supports pagination.
      parameters:
      - schema:
          type: integer
          default: 50
        in: query
        name: limit
        required: false
        description: Max results to return (clamped to 100)
      - schema:
          type: integer
          default: 0
        in: query
        name: offset
        required: false
        description: Number of results to skip
      responses:
        '200':
          description: List of pods
          content:
            application/json:
              schema:
                description: List of pods
                type: object
                additionalProperties: true
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pod'
                  total:
                    type: integer
        '401':
          description: Missing, invalid, or expired API key
          content:
            application/json:
              schema:
                description: Missing, invalid, or expired API key
                allOf:
                - $ref: '#/components/schemas/Error'
  /v1/pods/{id}:
    get:
      operationId: getPod
      summary: Get pod
      tags:
      - Pods
      description: Retrieve a single pod by its OpenMail ID or your own `clientId`.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: Pod ID or your own `clientId`
      responses:
        '200':
          description: Pod details
          content:
            application/json:
              schema:
                description: Pod details
                allOf:
                - $ref: '#/components/schemas/Pod'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Not found
                allOf:
                - $ref: '#/components/schemas/Error'
    patch:
      operationId: updatePod
      summary: Update pod
      tags:
      - Pods
      description: Update a pod's `clientId` or `name`. Only the fields you include are changed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                clientId:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  description: Your own identifier for this pod. Set null to clear.
                name:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  description: Human-readable label. Set null to clear.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: Pod ID or your own `clientId`
      responses:
        '200':
          description: Pod updated
          content:
            application/json:
              schema:
                description: Pod updated
                allOf:
                - $ref: '#/components/schemas/Pod'
        '403':
          description: The authenticating key is pod-scoped and cannot modify pods
          content:
            application/json:
              schema:
                description: The authenticating key is pod-scoped and cannot modify pods
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Not found
                allOf:
                - $ref: '#/components/schemas/Error'
        '409':
          description: A pod with the same `clientId` already exists in your account
          content:
            application/json:
              schema:
                description: A pod with the same `clientId` already exists in your account
                allOf:
                - $ref: '#/components/schemas/Error'
    delete:
      operationId: deletePod
      summary: Delete pod
      tags:
      - Pods
      description: Permanently delete a pod. The pod must be empty (no inboxes or pod-scoped domains) and cannot be the default pod.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: Pod ID or your own `clientId`
      responses:
        '204':
          description: Pod deleted
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Not found
                allOf:
                - $ref: '#/components/schemas/Error'
        '409':
          description: Pod still has inboxes (`pod_not_empty`), still owns pod-scoped domains (`pod_has_domains`), or is the default pod (`default_pod`)
          content:
            application/json:
              schema:
                description: Pod still has inboxes (`pod_not_empty`), still owns pod-scoped domains (`pod_has_domains`), or is the default pod (`default_pod`)
                allOf:
                - $ref: '#/components/schemas/Error'
  /v1/pods/{id}/api-keys:
    post:
      operationId: createPodApiKey
      summary: Create pod API key
      tags:
      - Pods
      description: Mint an API key scoped to this pod. The key can read and send from the pod's inboxes, create and delete inboxes in this pod, mint/revoke inbox keys for those inboxes, and manage pod/inbox policy and pod-scoped domains. It cannot change webhook config, manage pods, mint further pod keys, reach another pod, or address account-wide policy or domains. The full `token` is returned once, here — store it securely, it cannot be retrieved again. Requires an account-wide key (a pod-scoped key cannot mint keys).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  description: Human-readable label to identify the key later.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: Pod ID or your own `clientId`
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                description: API key created
                allOf:
                - $ref: '#/components/schemas/ApiKeyWithToken'
        '403':
          description: The authenticating key is pod-scoped and cannot mint keys
          content:
            application/json:
              schema:
                description: The authenticating key is pod-scoped and cannot mint keys
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Pod not found
          content:
            application/json:
              schema:
                description: Pod not found
                allOf:
                - $ref: '#/components/schemas/Error'
        '422':
          description: The pod already has the maximum number of active keys (`api_key_limit_reached`)
          content:
            application/json:
              schema:
                description: The pod already has the maximum number of active keys (`api_key_limit_reached`)
                allOf:
                - $ref: '#/components/schemas/Error'
    get:
      operationId: listPodApiKeys
      summary: List pod API keys
      tags:
      - Pods
      description: List the (non-revoked) API keys scoped to this pod. Only non-secret fields are returned — the token itself is never retrievable after creation.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: Pod ID or your own `clientId`
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                description: List of API keys
                type: object
                additionalProperties: true
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
        '403':
          description: The authenticating key is pod-scoped and cannot manage keys
          content:
            application/json:
              schema:
                description: The authenticating key is pod-scoped and cannot manage keys
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Pod not found
          content:
            application/json:
              schema:
                description: Pod not found
                allOf:
                - $ref: '#/components/schemas/Error'
  /v1/pods/{id}/api-keys/{keyId}:
    delete:
      operationId: deletePodApiKey
      summary: Revoke pod API key
      tags:
      - Pods
      description: Permanently revoke a pod-scoped API key. Any integration using it immediately starts getting 401s. Requires an account-wide key.
      parameters:
      - schema:
          type: string
        in: path
        name: id
        required: true
        description: Pod ID or your own `clientId`
      - schema:
          type: string
        in: path
        name: keyId
        required: true
        description: The API key ID to revoke
      responses:
        '204':
          description: Key revoked
        '403':
          description: The authenticating key is pod-scoped and cannot manage keys
          content:
            application/json:
              schema:
                description: The authenticating key is pod-scoped and cannot manage keys
                allOf:
                - $ref: '#/components/schemas/Error'
        '404':
          description: Key not found
          content:
            application/json:
              schema:
                description: Key not found
                allOf:
                - $ref: '#/components/schemas/Error'
components:
  schemas:
    ApiKeyWithToken:
      type: object
      additionalProperties: true
      description: An API key plus its raw `token`. The token is returned only once, at creation, and is never retrievable again.
      allOf:
      - $ref: '#/components/schemas/ApiKey'
      properties:
        token:
          type: string
          description: The secret API key. Store it securely — it is shown only once and cannot be retrieved later.
    Error:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        message:
          type: string
    Pod:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: OpenMail pod ID
        clientId:
          type:
          - string
          - 'null'
          description: Your own identifier for the pod, if set.
        name:
          type:
          - string
          - 'null'
          description: Human-readable label, if set.
        isDefault:
          type: boolean
          description: Whether this is the account's default pod. Every account has exactly one; it is created automatically and cannot be deleted.
        createdAt:
          type: string
          format: date-time
    ApiKey:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: OpenMail API key ID
        name:
          type:
          - string
          - 'null'
          description: Human-readable label for the key, if set.
        podId:
          type:
          - string
          - 'null'
          description: ID of the pod this key is scoped to, or null for an account-wide key. A pod-scoped key can only access resources in this pod.
        inboxId:
          type:
          - string
          - 'null'
          description: ID of the inbox this key is confined to, or null. When set, the key can only access this single inbox and its threads, messages, and drafts (its `podId` is the inbox's pod).
        tokenPrefix:
          type: string
          description: Non-secret leading characters of the token, to help you identify it.
        last4:
          type: string
          description: Last 4 characters of the token, shown alongside the prefix.
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: When the key last authenticated a request, or null if never used.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key