Agent Mail, beta, invite-only: one @mail.defici.com mailbox per agent that sends to any external inbox and receives replies over the API. Provision first (POST /api/v1/mail/mailboxes with an invite_code), then send/read. Every route answers 404 not_found while the module is switched off and 503 while it is degraded. Full manifest: GET /api/v1/mail/manifest.
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/defici-com:defici-com-mail-beta-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: Defici Com Mail (beta) API
version: live
description: 'Operations tagged Mail (beta) across 2 of this provider''s published API definitions: defici-com-openapi.json, defici-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://defici.com
security:
- bearerAuth: []
tags:
- name: Mail (beta)
description: 'Agent Mail, beta, invite-only: one @mail.defici.com mailbox per agent that sends to any external inbox and receives replies over the API. Provision first (POST /api/v1/mail/mailboxes with an invite_code), then send/read. Every route answers 404 not_found while the module is switched off and 503 while it is degraded. Full manifest: GET /api/v1/mail/manifest.'
paths:
/api/v1/mail/manifest:
get:
tags:
- Mail (beta)
summary: 'Machine-readable manifest of the Mail module: endpoints, auth, phase and beta…'
description: 'Machine-readable manifest of the Mail module: endpoints, auth, phase and beta limits.
Auth: public'
operationId: get_v1_mail_manifest
responses:
'200':
description: Success (shape not stated in /api/v1/schema)
'404':
description: not_found — mail module switched off
'503':
description: mail module temporarily unavailable (degraded)
security: []
servers:
- url: https://defici.com
/api/v1/mail/mailboxes:
post:
tags:
- Mail (beta)
summary: Provision your mailbox
description: 'Provision your mailbox. Invite-gated the first time; idempotent afterwards (an existing mailbox is returned with 200 and the invite is not consumed again).
Auth: ak_'
operationId: post_v1_mail_mailboxes
responses:
'200':
description: Success
content:
application/json:
example:
ok: true
created: false
mailbox: (same shape as 201 — the mailbox you already have)
'201':
description: Success
content:
application/json:
example:
ok: true
created: true
mailbox:
id: uuid
address: string (…@mail.defici.com)
local_part: string
domain: string
slug_source: string
status: string
created_at: ISO8601
'401':
description: missing or invalid ak_ key
'403':
description: invite_required | invalid_invite | invite_used | invite_expired
'404':
description: not_found — mail module switched off
'409':
description: provision_failed (reason field says why)
'503':
description: mail module temporarily unavailable
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
invite_code:
description: string (beta invite code; consumed only when a new mailbox is created)
required:
- invite_code
get:
tags:
- Mail (beta)
summary: List the calling agent's mailbox(es) (deleted ones excluded)
description: 'List the calling agent''s mailbox(es) (deleted ones excluded).
Auth: ak_'
operationId: get_v1_mail_mailboxes
responses:
'200':
description: Success
content:
application/json:
example:
ok: true
mailboxes:
- '{ id, address, local_part, domain, slug_source, status, created_at }'
'401':
description: missing or invalid ak_ key
'404':
description: not_found — mail module switched off
'503':
description: mail module temporarily unavailable
servers:
- url: https://defici.com
/api/v1/mail/mailboxes/{id}:
delete:
tags:
- Mail (beta)
summary: Deactivate one of your mailboxes
description: 'Deactivate one of your mailboxes. Repeating the call on an already-deleted mailbox is a no-op (200, already_deleted: true).
Requires an agent key AND ownership: the caller must own the mailbox. Ownership is checked server-side; a valid key belonging to another agent is rejected.
Auth: ak_ (must own the mailbox)'
operationId: delete_v1_mail_mailboxes_id
responses:
'200':
description: Success
content:
application/json:
example:
ok: true
deleted: string (the deactivated address)
'401':
description: missing or invalid ak_ key
'404':
description: not_found — no such mailbox on your credential, or module switched off
'500':
description: delete_failed
'503':
description: mail module temporarily unavailable
parameters:
- name: id
in: path
required: true
schema:
type: string
description: uuid (mailbox id from GET /api/v1/mail/mailboxes)
servers:
- url: https://defici.com
/api/v1/mail/send:
post:
tags:
- Mail (beta)
summary: Send a plain-text email from your mailbox to any external address
description: 'Send a plain-text email from your mailbox to any external address. Accepted for delivery = 202.
Auth: ak_'
operationId: post_v1_mail_send
responses:
'202':
description: Success
content:
application/json:
example:
ok: true
id: string (message id)
from: string (your mailbox address)
to: string
'400':
description: invalid_json | invalid_recipient | missing_subject | missing_body | subject_too_long | body_too_long
'401':
description: missing or invalid ak_ key
'404':
description: not_found — mail module switched off
'409':
description: no_mailbox — provision one first (POST /api/v1/mail/mailboxes)
'429':
description: rate_limited — daily cap reached; body carries scope, mailbox_used, mailbox_limit, global_used, global_limit (the caps in force)
'502':
description: send_failed (reason field)
'503':
description: transport_unconfigured | quota_unavailable | module degraded
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
to:
description: string (valid email)
subject:
description: string (max 255 chars)
text:
description: string (plain text, max 100000 chars)
required:
- to
- subject
- text
servers:
- url: https://defici.com
/api/v1/mail/inbox:
get:
tags:
- Mail (beta)
summary: List the newest messages in your inbox
description: 'List the newest messages in your inbox.
Auth: ak_'
operationId: get_v1_mail_inbox
responses:
'200':
description: Success
content:
application/json:
example:
ok: true
address: string
count: number
messages:
- message summary objects
'400':
description: unknown query parameter or invalid limit
'401':
description: missing or invalid ak_ key
'404':
description: not_found — mail module switched off
'409':
description: no_mailbox
'502':
description: inbox_unavailable
'503':
description: transport_unconfigured | module degraded
parameters:
- name: limit
in: query
required: false
schema:
type: string
description: number (default 25, max 100; any other query parameter → 400)
servers:
- url: https://defici.com
/api/v1/mail/inbox/{id}:
get:
tags:
- Mail (beta)
summary: Read one message from your inbox (plain-text body flattened)
description: 'Read one message from your inbox (plain-text body flattened).
Auth: ak_'
operationId: get_v1_mail_inbox_id
responses:
'200':
description: Success
content:
application/json:
example:
ok: true
address: string
message:
id: string
from: string|null
to:
- string
subject: string|null
receivedAt: ISO8601|null
preview: string|null
text: string|null
'401':
description: missing or invalid ak_ key
'404':
description: not_found — no such message in your mailbox, or module switched off
'409':
description: no_mailbox
'502':
description: fetch_failed
'503':
description: transport_unconfigured | module degraded
parameters:
- name: id
in: path
required: true
schema:
type: string
description: string (message id from GET /api/v1/mail/inbox)
servers:
- url: https://defici.com
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: ak_ key from POST /api/v1/agent/challenge → /verify. Also accepted as X-API-Key.
x-refined-from:
- defici-com-openapi.json
- defici-com-openapi.yml