Mail API
API-first email service for AI agents. Provision mailboxes, send and receive messages, manage threads, search by full-text, and subscribe to events via webhooks.
API base URL:
https://inkbox.ai/api/v1/mailQuick start
Create an account and get your API key from the Inkbox console:
All API requests require authentication using a API key:
X-API-Key: YOUR_API_KEYMailboxes
Mailboxes are owned 1:1 by an agent identity — they're created and destroyed atomically with the identity. To provision a mailbox, create an identity; to remove one, delete the identity.
List mailboxes
GETList all mailboxes for your organization
/api/v1/mail/mailboxesGet mailbox
GETGet a single mailbox by email address
/api/v1/mail/mailboxes/{email_address}Update mailbox
PATCHUpdate a mailbox (filter mode now lives on the identity)
/api/v1/mail/mailboxes/{email_address}Messages
List messages
GETList messages in a mailbox with cursor pagination
/api/v1/mail/mailboxes/{email_address}/messagesGet message
GETGet a message with full body content
/api/v1/mail/mailboxes/{email_address}/messages/{message_id}Send message
POSTCompose and send an email
/api/v1/mail/mailboxes/{email_address}/messagesForward message
POSTForward a stored message (inline or wrapped) — creates a new thread
/api/v1/mail/mailboxes/{email_address}/messages/{message_id}/forwardUpdate message flags
PATCHUpdate is_read or is_starred on a message
/api/v1/mail/mailboxes/{email_address}/messages/{message_id}Delete message
DELETEDelete a message
/api/v1/mail/mailboxes/{email_address}/messages/{message_id}Download attachment
GETDownload a message attachment
/api/v1/mail/mailboxes/{email_address}/messages/{message_id}/attachments/{filename}Branding footer
Sent, replied, and forwarded emails include a short "Sent via Inkbox" footer
by default. Paid organizations can remove it org-wide with
PUT /api/v1/billing/settings and {"remove_branding_footer": true} (admin
API key, or from the Inkbox Console Email
page); the current value appears in GET /api/v1/billing/settings. On the
Free plan the footer always applies and the update returns 403. The footer
appears in the delivered email and the stored message body, but never in
message snippets or search results.
Threads
List threads
GETList threads with cursor pagination, most recent activity first
/api/v1/mail/mailboxes/{email_address}/threadsGet thread
GETGet a thread with all its messages inline
/api/v1/mail/mailboxes/{email_address}/threads/{thread_id}Delete thread
DELETEDelete a thread
/api/v1/mail/mailboxes/{email_address}/threads/{thread_id}Search
Search messages (mailbox)
GETFull-text search across messages in a mailbox, ranked by relevance
/api/v1/mail/mailboxes/{email_address}/searchSearch messages (org-wide)
GETFull-text search across all mailboxes in your organization
/api/v1/mail/searchContact rules
Per-identity allow and block rules interpreted against the identity's mail_filter_mode (blacklist by default, whitelist on demand). Rules attach to the agent identity and are addressed by agent_handle. See the Contact rules reference and the Email guide for semantics.
The previous mailbox-addressed routes (/mail/mailboxes/{email_address}/contact-rules) are deprecated — migrate to the identity-keyed routes below.
List contact rules
GETList allow/block rules for an agent identity
/api/v1/identities/{agent_handle}/mail-contact-rulesCreate contact rule
POSTAdd an allow or block rule (exact email or domain)
/api/v1/identities/{agent_handle}/mail-contact-rulesGet contact rule
GETFetch a single rule by ID
/api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}Update contact rule
PATCHChange a rule's action (admin-only)
/api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}Delete contact rule
DELETEDelete a rule (admin-only)
/api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}List org mail contact rules
GETOrg-wide aggregate list across every identity (admin-only)
/api/v1/mail/contact-rulesWebhooks
Mail event delivery is configured via the Webhook Subscriptions API — attach one or more subscriptions to the mailbox with the subset of message.* events you want. See the Webhooks guide for event types, payload format, and signature verification.
Filtering by date
Date filtering applies to one list endpoint — List messages (GET /mailboxes/{email_address}/messages). It accepts three optional query parameters that filter results by when each message was created (created_at, stored in UTC); other mail list endpoints (such as list mailboxes and list contact rules) do not support them. All three are optional and fully backwards-compatible — omit them and the endpoint behaves exactly as before, with no filtering applied.
| Parameter | Type | Default | Description |
|---|---|---|---|
start_datetime | string | — | Inclusive lower bound. A bare date (2026-07-01) starts at 00:00 of that day; a datetime with a Z or offset is used as an exact instant |
end_datetime | string | — | Upper bound, inclusive. A bare date (2026-07-06) covers the whole day; a datetime with a Z or offset is an exact instant, and records created at exactly that instant are included |
tz | string | UTC | IANA time zone (e.g. America/New_York) used to interpret zone-less values. Defaults to UTC |
- A bare date in
end_datetimeis inclusive of the entire day —end_datetime=2026-07-06returns records through the last moment of the 6th. - A datetime with an explicit
Zor offset (2026-07-06T15:30:00Z,2026-07-06T11:30:00-04:00) is an exact instant;tzis ignored for that value. - A naive datetime (
2026-07-01T12:00:00) is interpreted intz(UTC whentzis omitted). - Supply only one side for an open-ended range. Ordering, pagination, and all other filters are unchanged.
- Invalid input returns
422:start_datetimeafterend_datetime, an unparseable date, or an unknown time zone.
A bare-date range (interpreted in UTC):
?start_datetime=2026-07-01&end_datetime=2026-07-06Interpret those bare dates in a specific zone:
?start_datetime=2026-07-01&end_datetime=2026-07-06&tz=America/New_YorkFilter from an exact instant (tz ignored):
?start_datetime=2026-07-06T15:30:00Z