Botmail Account API
The signed-in account, identities, usage, deletion and export.
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/botmail-pro:botmail-pro-account-api"
All apis
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.
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: Botmail Account API
version: 1.0.0
summary: Gmail for AI agents.
description: 'Real email mailboxes for AI agents. Agents claim an address with
`POST /v1/claim`, a human claims it in the browser, then the same API key
reads, sends and manages mail.
**Errors** always look like `{"error": {"code", "message", "hint?", "details?"}}`.
`code` is stable and machine-readable; `hint` says what to do next.
429 responses carry `Retry-After` (seconds).
**IDs** are prefixed strings: `acct_`, `mbx_`, `thr_`, `msg_`, `key_`, `clm_`.
Times are RFC 3339 UTC.
**Scopes**: `read`, `send`, `manage`. Pending claim keys (`bm_pending_…`)
have `read` + `invite` until a human claims the mailbox, then they gain
full access in place. `send` is dropped while the account is not `active`.
Each operation lists its required scope.'
servers:
- url: https://botmail.pro
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: Account
description: The signed-in account, identities, usage, deletion and export.
paths:
/v1/me:
get:
tags:
- Account
operationId: getMe
summary: Current account and credential
description: 'Scope: any. Pending claim keys allowed.'
responses:
'200':
description: The account, its sign-in identities and the calling credential.
content:
application/json:
schema:
$ref: '#/components/schemas/Me'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/me/identities/{id}:
delete:
tags:
- Account
operationId: unlinkIdentity
summary: Unlink a sign-in provider
description: 'Scope: manage. Not for pending keys. The last identity can''t be removed (409 last_identity).'
parameters:
- $ref: '#/components/parameters/IdPath'
responses:
'200':
description: Removed.
content:
application/json:
schema:
type: object
required:
- id
- removed
properties:
id:
type: string
removed:
type: boolean
const: true
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
/v1/account/usage:
get:
tags:
- Account
operationId: getUsage
summary: Plan, storage and send allowance
description: 'Scope: any. Pending claim keys allowed.'
responses:
'200':
description: Usage and limits.
content:
application/json:
schema:
$ref: '#/components/schemas/Usage'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/account:
delete:
tags:
- Account
operationId: deleteAccount
summary: Schedule account deletion
description: 'Signed-in human (session cookie) only. Starts a 30-day grace period:
sending stops, API keys and OAuth tokens are revoked, mail still arrives.
Body must be `{"confirm": "DELETE MY ACCOUNT"}` (else 400 confirmation_required).'
security:
- cookieAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- confirm
additionalProperties: false
properties:
confirm:
type: string
const: DELETE MY ACCOUNT
responses:
'202':
description: Deletion scheduled.
content:
application/json:
schema:
type: object
required:
- status
- due_at
- hint
properties:
status:
type: string
const: scheduled
due_at:
type: string
format: date-time
hint:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
/v1/account/deletion:
get:
tags:
- Account
operationId: getDeletion
summary: Deletion status
description: 'Scope: read. Not for pending keys.'
responses:
'200':
description: 'Deletion status (`scheduled: false` when none).'
content:
application/json:
schema:
$ref: '#/components/schemas/DeletionStatus'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/account/deletion/cancel:
post:
tags:
- Account
operationId: cancelDeletion
summary: Cancel a scheduled deletion
description: 'Signed-in human only. Restores the prior account status and the API
keys and OAuth tokens the deletion revoked (keys revoked earlier stay
revoked). 404 not_scheduled, 409 deletion_in_progress.'
security:
- cookieAuth: []
responses:
'200':
description: Cancelled.
content:
application/json:
schema:
type: object
required:
- status
- hint
properties:
status:
type: string
const: cancelled
hint:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
/v1/account/export:
post:
tags:
- Account
operationId: createExport
summary: Start a data export
description: 'Scope: manage. Not for pending keys. Builds a zip (mbox + JSON); a
download link is emailed when ready. One export per hour (429).'
responses:
'202':
description: Export queued.
content:
application/json:
schema:
type: object
required:
- id
- status
- created_at
- hint
properties:
id:
type: string
status:
type: string
const: pending
created_at:
type: string
format: date-time
hint:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
/v1/account/exports:
get:
tags:
- Account
operationId: listExports
summary: List exports
description: 'Scope: manage. Not for pending keys.'
responses:
'200':
description: Exports, newest first.
content:
application/json:
schema:
type: object
required:
- exports
properties:
exports:
type: array
items:
$ref: '#/components/schemas/Export'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/v1/account/exports/{id}/download:
get:
tags:
- Account
operationId: downloadExport
summary: Download an export
description: 'Scope: manage. Redirects to a presigned URL valid for 15 minutes. 404 if not ready or expired.'
parameters:
- $ref: '#/components/parameters/IdPath'
responses:
'302':
description: Redirect to the zip.
headers:
Location:
schema:
type: string
format: uri
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/v1/feedback:
post:
tags:
- Account
operationId: sendFeedback
summary: Report a problem with Botmail
description: 'Any credential, including pending claim keys. Tell the Botmail team
about a bug, a confusing error or instruction, a missing feature, or
mail not arriving. A human reads every report. 20 per account per day
(429). Same as the botmail_feedback MCP tool. Errors: 400 bad_category
/ empty_feedback / feedback_too_long.'
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- message
additionalProperties: false
properties:
category:
type: string
enum:
- bug
- confusing
- feature
- deliverability
- other
default: other
message:
type: string
maxLength: 4000
description: What happened, what you expected, what you tried.
context:
type: string
maxLength: 2000
description: Tool or endpoint, error code, related IDs.
mailbox_id:
type: string
responses:
'201':
description: Received.
content:
application/json:
schema:
type: object
required:
- id
- received
properties:
id:
type: string
received:
type: boolean
hint:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
components:
responses:
Conflict:
description: Conflicts with current state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Invalid request (`bad_request` or a more specific code).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Missing or invalid credentials (`unauthorized`, `invalid_token`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: 'The credential can''t do this (`forbidden`, `csrf`, `account_inactive`, …).
Missing scopes are listed in `details.required_scope`; pending keys get
a hint to wait for the claim.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Not found or not accessible with this credential.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
RateLimited:
description: Too many requests (`rate_limited`, `invite_limit`). Wait `Retry-After` seconds.
headers:
Retry-After:
description: Seconds to wait.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable machine-readable code, e.g. `not_found`, `name_taken`, `rate_limited`.
message:
type: string
hint:
type: string
description: What to do next.
details:
type: object
additionalProperties: true
Usage:
type: object
required:
- plan
- kind
- status
- limits
- used_bytes
- quota_bytes
- extra_storage_bytes
- over_quota
- mailboxes
properties:
plan:
$ref: '#/components/schemas/Plan'
kind:
type: string
enum:
- human
- pending
status:
type: string
enum:
- active
- receive_only
- suspended
- deleting
limits:
$ref: '#/components/schemas/Limits'
used_bytes:
type: integer
format: int64
quota_bytes:
type: integer
format: int64
extra_storage_bytes:
type: integer
format: int64
over_quota:
type: boolean
description: New mail is held while true.
mailboxes:
type: object
required:
- used
- limit
properties:
used:
type: integer
limit:
type: integer
sends_today:
$ref: '#/components/schemas/Allowance'
description: Omitted if the allowance lookup fails.
Identity:
type: object
required:
- id
- provider
- email_verified
- is_private_relay
- created_at
- last_login_at
properties:
id:
type: string
provider:
type: string
examples:
- google
- apple
- github
- microsoft
email:
type: string
email_verified:
type: boolean
is_private_relay:
type: boolean
created_at:
type: string
format: date-time
last_login_at:
type:
- string
- 'null'
format: date-time
DeletionStatus:
type: object
required:
- scheduled
- in_progress
properties:
scheduled:
type: boolean
requested_at:
type: string
format: date-time
due_at:
type: string
format: date-time
in_progress:
type: boolean
description: Deletion has started and can't be cancelled.
Limits:
type: object
required:
- plan
- price_usd
- mailboxes
- storage_bytes
- all_domains
- short_names
- start_new_recipients
- max_new_recipients
- max_total_per_day
- custom_domains
- storage_addon_allowed
properties:
plan:
$ref: '#/components/schemas/Plan'
price_usd:
type: integer
description: Per month.
mailboxes:
type: integer
storage_bytes:
type: integer
format: int64
all_domains:
type: boolean
description: Same name on every Botmail domain.
short_names:
type: boolean
description: Names of 4 characters or fewer.
start_new_recipients:
type: integer
description: New recipients per day at the starting trust level.
max_new_recipients:
type: integer
description: Plan ceiling for new recipients per day.
max_total_per_day:
type: integer
custom_domains:
type: integer
storage_addon_allowed:
type: boolean
Plan:
type: string
enum:
- free
- pro
- team
- scale
Allowance:
type: object
required:
- level
- new_recipients_per_day
- total_per_day
- new_recipients_used
- total_used
properties:
level:
type: integer
description: Trust level 0-3.
new_recipients_per_day:
type: integer
total_per_day:
type: integer
new_recipients_used:
type: integer
total_used:
type: integer
Export:
type: object
required:
- id
- status
- created_at
properties:
id:
type: string
status:
type: string
enum:
- pending
- ready
- failed
- expired
created_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
download_url:
type: string
format: uri
ErrorResponse:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/Error'
Account:
type: object
required:
- id
- kind
- plan
- status
- trust_level
- risk_score
- used_bytes
- extra_storage_bytes
- is_staff
- created_at
properties:
id:
type: string
kind:
type: string
enum:
- human
- pending
plan:
$ref: '#/components/schemas/Plan'
status:
type: string
enum:
- active
- receive_only
- suspended
- deleting
trust_level:
type: integer
minimum: 0
maximum: 3
risk_score:
type: number
used_bytes:
type: integer
format: int64
extra_storage_bytes:
type: integer
format: int64
primary_email:
type: string
display_name:
type: string
is_staff:
type: boolean
created_at:
type: string
format: date-time
Me:
type: object
required:
- account
- identities
- staff
- providers
- auth
properties:
account:
$ref: '#/components/schemas/Account'
identities:
type: array
items:
$ref: '#/components/schemas/Identity'
staff:
type: boolean
providers:
type: array
description: Sign-in providers enabled on this server.
items:
type: string
auth:
type: object
description: The calling credential.
required:
- kind
- scopes
- mailbox_ids
- client_id
- staff
properties:
kind:
type: string
enum:
- session
- api_key
- oauth
- pending
scopes:
type:
- array
- 'null'
items:
type: string
mailbox_ids:
type: array
description: Empty = every mailbox in the account.
items:
type: string
client_id:
type: string
description: OAuth client id
or empty.: null
staff:
type: boolean
parameters:
IdPath:
name: id
in: path
required: true
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: '`Authorization: Bearer <key>` with an API key (`bm_live_…`) or a
pending claim key (`bm_pending_…`). OAuth 2.1 access tokens
(`bm_oat_…`) are audience-bound to the MCP endpoint `/mcp` and are
rejected on `/v1`; MCP clients discover OAuth via
`/.well-known/oauth-protected-resource/mcp`.
'
cookieAuth:
type: apiKey
in: cookie
name: bm_session
description: 'Web session for signed-in humans. Non-GET requests must send a JSON
`Content-Type` or `X-Botmail-CSRF: 1` (403 csrf otherwise).
'