openmail-sh Pods API
Isolated sub-accounts for your end users or tenants
Isolated sub-accounts for your end users or tenants
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/openmail-sh:openmail-sh-pods-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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.
A second provider on the same verified email joins the account you already have.
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