Skip to main content
API-first email service for AI agents. Provision mailboxes, import historical mail, save drafts, send and receive messages, manage threads, search by full-text, and subscribe to events via webhooks. API base URL:

​
Quick start

Create an account and get your API key from the Inkbox console:

Get API key

All API requests require authentication using a API key:

​
Mailboxes

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

List all mailboxes for your organizationGET /api/v1/mail/mailboxes

Get mailbox

Get a single mailbox by email addressGET /api/v1/mail/mailboxes/{email_address}

Update mailbox

Configure a custom email signature (filter mode now lives on the identity)PATCH /api/v1/mail/mailboxes/{email_address}

​
Imports

Import historical email from MBOX, EML, or ZIP archives. Imports run asynchronously and expose status plus per-message counters.

Create import

Create an import job and receive an upload targetPOST /api/v1/mail/mailboxes/{email_address}/imports

Refresh upload target

Re-issue the upload target for a job awaiting its filePOST /api/v1/mail/mailboxes/{email_address}/imports/{job_id}/upload-url

Start import

Queue an uploaded MBOX, EML, or ZIP file for processingPOST /api/v1/mail/mailboxes/{email_address}/imports/{job_id}/start

Get import

Poll an import job’s status and countersGET /api/v1/mail/mailboxes/{email_address}/imports/{job_id}

List imports

List a mailbox’s import jobs with cursor paginationGET /api/v1/mail/mailboxes/{email_address}/imports

Cancel import

Cancel an active import jobPOST /api/v1/mail/mailboxes/{email_address}/imports/{job_id}/cancel

​
Messages

List messages

List messages in a mailbox with cursor paginationGET /api/v1/mail/mailboxes/{email_address}/messages

Get message

Get a message with full body contentGET /api/v1/mail/mailboxes/{email_address}/messages/{message_id}

Send message

Compose and send an emailPOST /api/v1/mail/mailboxes/{email_address}/messages

Forward message

Forward a stored message (inline or wrapped) — creates a new threadPOST /api/v1/mail/mailboxes/{email_address}/messages/{message_id}/forward

Update message flags

Update is_read or is_starred on a messagePATCH /api/v1/mail/mailboxes/{email_address}/messages/{message_id}

Delete message

Delete a messageDELETE /api/v1/mail/mailboxes/{email_address}/messages/{message_id}

Download attachment

Download a message attachmentGET /api/v1/mail/mailboxes/{email_address}/messages/{message_id}/attachments/{filename}

​
Drafts

Save incomplete email, revise it safely with generations, manage attachments, and send the final revision. See the Drafts reference for the complete lifecycle.

Create draft

Save an incomplete or complete draftPOST /api/v1/mail/mailboxes/{email_address}/drafts

List drafts

List drafts newest-update firstGET /api/v1/mail/mailboxes/{email_address}/drafts

Get draft

Get bodies, headers, and attachment descriptorsGET /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}

Update draft

Partially update an expected generationPATCH /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}

Add draft attachments

Add generation-scoped attachmentsPOST /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}/attachments

Remove draft attachment

Remove an attachment from the expected generationDELETE /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}/attachments/{part_index}

Download draft attachment

Download an attachment from the expected generationGET /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}/attachments/{part_index}

Duplicate draft

Copy an exact revision into a new draftPOST /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}/duplicate

Send draft

Validate and send the expected generationPOST /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}/send

Delete draft

Delete the expected generationDELETE /api/v1/mail/mailboxes/{email_address}/drafts/{draft_id}
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

List threads with cursor pagination, most recent activity firstGET /api/v1/mail/mailboxes/{email_address}/threads

Get thread

Get a thread with all its messages inlineGET /api/v1/mail/mailboxes/{email_address}/threads/{thread_id}

Delete thread

Delete a threadDELETE /api/v1/mail/mailboxes/{email_address}/threads/{thread_id}

Search messages (mailbox)

Full-text search across messages in a mailbox, ranked by relevanceGET /api/v1/mail/mailboxes/{email_address}/search

Search messages (org-wide)

Full-text search across all mailboxes in your organizationGET /api/v1/mail/search

​
Contact 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

List allow/block rules for an agent identityGET /api/v1/identities/{agent_handle}/mail-contact-rules

Create contact rule

Add an allow or block rule (exact email or domain)POST /api/v1/identities/{agent_handle}/mail-contact-rules

Get contact rule

Fetch a single rule by IDGET /api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}

Update contact rule

Change a rule’s action (admin-only)PATCH /api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}

Delete contact rule

Delete a rule (admin-only)DELETE /api/v1/identities/{agent_handle}/mail-contact-rules/{rule_id}

List org mail contact rules

Org-wide aggregate list across every identity (admin-only)GET /api/v1/mail/contact-rules

​
Webhooks

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.
  • A bare date in end_datetime is inclusive of the entire day — end_datetime=2026-07-06 returns records through the last moment of the 6th.
  • A datetime with an explicit Z or offset (2026-07-06T15:30:00Z, 2026-07-06T11:30:00-04:00) is an exact instant; tz is ignored for that value.
  • A naive datetime (2026-07-01T12:00:00) is interpreted in tz (UTC when tz is omitted).
  • Supply only one side for an open-ended range. Ordering, pagination, and all other filters are unchanged.
  • Invalid input returns 422: start_datetime after end_datetime, an unparseable date, or an unknown time zone.
A bare-date range (interpreted in UTC):
Interpret those bare dates in a specific zone:
Filter from an exact instant (tz ignored):

​
Additional resources