agentboxd-com Inboxes API
Email addresses for agents: create, list, pause and delete them.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/agentboxd-com:agentboxd-com-inboxes-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.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Agentboxd Com Inboxes API
version: '1'
contact:
name: Agentboxd
url: https://agentboxd.com
email: hello@agentboxd.com
description: 'Operations tagged Inboxes across 2 of this provider''s published API definitions: agentboxd-com-openapi.json, agentboxd-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentboxd.com
security:
- apiKey: []
tags:
- name: Inboxes
description: 'Email addresses for agents: create, list, pause and delete them.'
paths:
/v1/inboxes:
post:
operationId: postInboxes
tags:
- Inboxes
summary: Create an inbox
description: '`{ username?, display_name?, client_id?, metadata?, domain? }`. Random readable username if omitted. Idempotent on `client_id` (200 with the existing inbox). `domain` is one of your verified domains (default `homingbox.net`; our other domains, such as `agents.agentboxd.com`, get no new inboxes: `400 invalid_domain`). Send `{ ttl_seconds }` (60–86 400) instead for a temporary inbox; `username`, `domain` and `client_id` are not allowed with it. `card` (the agent card fields) creates the inbox and its card in one call and returns it as `card`; it needs `directory:write` too, is checked before the inbox is created, and is refused on temporary inboxes (`403 identity_unavailable`).
Permission: `inboxes:write`.'
x-permission: inboxes:write
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
minLength: 1
maxLength: 64
display_name:
type: string
minLength: 1
maxLength: 128
client_id:
type: string
minLength: 1
maxLength: 255
metadata:
type: object
propertyNames:
type: string
pattern: ^[a-zA-Z0-9_.-]{1,64}$
additionalProperties:
anyOf:
- type: string
maxLength: 1000
- type: number
- type: boolean
- type: 'null'
domain:
type: string
minLength: 1
maxLength: 253
ttl_seconds:
type: integer
minimum: 60
maximum: 86400
card:
type: object
propertyNames:
type: string
additionalProperties: {}
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
4XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
get:
operationId: getInboxes
tags:
- Inboxes
summary: List inboxes
description: 'List inboxes. Filter on your own fields with `?metadata.=` (exact string match). Temporary inboxes are left out unless you pass `?include_temporary=true`; `?temporary=true` lists only them. Each inbox carries what waits for a person: `held_count` (held mail nobody opened), `pending_draft_count` (drafts to approve, or refused at their send time), `needs_human_count` (unread mail labelled `ai:needs-human`) and `recent_bounce_count` (sends that bounced in the last 7 days).
Permission: `inboxes:read`.'
x-permission: inboxes:read
parameters:
- name: cursor
in: query
required: false
schema:
type: string
- name: limit
in: query
required: false
schema:
default: 25
type: integer
minimum: 1
maximum: 100
- name: include_temporary
in: query
required: false
schema:
type: string
enum:
- 'true'
- 'false'
- name: temporary
in: query
required: false
schema:
type: string
enum:
- 'true'
- 'false'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
4XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://api.agentboxd.com
/v1/inboxes/{id}:
get:
operationId: getInboxesById
tags:
- Inboxes
summary: Get an inbox
description: 'One inbox, with its `metadata` and the same counts as the list. Every inbox has `temporary` (boolean) and `expires_at` (ISO time, or null).
Permission: `inboxes:read`.'
x-permission: inboxes:read
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
4XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
operationId: patchInboxesById
tags:
- Inboxes
summary: Update an inbox
description: '`{ display_name?, metadata?, ttl_seconds?, promotions_filter? }`. Metadata is merged; a `null` value deletes the key. See Metadata. `ttl_seconds` extends a temporary inbox, counted from now, up to 24 hours after it was created. `promotions_filter` turns the Promotions & spam view on or off; `null` goes back to the default (on for role addresses such as hello@ and support@).
Permission: `inboxes:write`.'
x-permission: inboxes:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
display_name:
anyOf:
- type: string
minLength: 1
maxLength: 128
- type: 'null'
metadata:
type: object
propertyNames:
type: string
pattern: ^[a-zA-Z0-9_.-]{1,64}$
additionalProperties:
anyOf:
- type: string
maxLength: 1000
- type: number
- type: boolean
- type: 'null'
ttl_seconds:
type: integer
minimum: 60
maximum: 86400
promotions_filter:
type:
- boolean
- 'null'
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
4XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: deleteInboxesById
tags:
- Inboxes
summary: Delete an inbox
description: 'Soft delete. The address is never reused. Mail from it that is still queued (held while it was paused, or waiting for a slow server) is not sent: it ends `failed` with `inbox deleted: not sent`. On a temporary inbox this wipes its messages, attachments and threads right away.
Permission: `inboxes:write`.'
x-permission: inboxes:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
4XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://api.agentboxd.com
/v1/inboxes/{id}/pause:
post:
operationId: postInboxesByIdPause
tags:
- Inboxes
summary: Pause sending from an inbox
description: '`{ reason? }` (up to 500 characters). The kill switch: every send from the inbox is refused with `423 inbox_paused` (send, reply, draft send, SMTP), and so is Sign in with Agentboxd for it. Inbound mail is still received and stored, but its `message.received` events and AI categorisation are held until you resume. Emits `inbox.paused`. Pausing a paused inbox changes nothing.
Permission: `inboxes:write`.'
x-permission: inboxes:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
maxLength: 500
additionalProperties: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
4XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://api.agentboxd.com
/v1/inboxes/{id}/resume:
post:
operationId: postInboxesByIdResume
tags:
- Inboxes
summary: Resume sending from an inbox
description: 'Sending works again. The held events are emitted in the order the mail arrived, after `inbox.resumed`; the response is the inbox plus `released_events`. Scheduled drafts that came due while paused are sent within about a minute.
Permission: `inboxes:write`.'
x-permission: inboxes:write
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
4XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://api.agentboxd.com
components:
schemas:
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable, machine-readable error code.
message:
type: string
description: What happened and how to fix it, in plain words.
details:
description: 'The specifics: which recipient, which limit, until when.'
docs_url:
type: string
format: uri
description: 'For a refused send: its entry on "Why was my send refused?" (https://agentboxd.com/docs/send-refusals).'
securitySchemes:
apiKey:
type: http
scheme: bearer
description: An API key (`mr_…`), scoped to the workspace or one inbox, with a set of permissions.
externalDocs:
description: API reference
url: https://agentboxd.com/docs/api
x-refined-from:
- agentboxd-com-openapi.json
- agentboxd-com-openapi.json