REST API
The same index, tools and coverage semantics as the MCP server, over plain HTTPS with a bearer key you can scope to specific mailboxes and to read-only.
curl -H "Authorization: Bearer aik_..." \
"https://emailgents.com/api/public/v1/messages?q=invoice&unread=true&limit=10"- Created under Agents in the app; shown once; prefixed aik_.
- Scope a key to chosen mailboxes and to read-only.
- Revoke instantly; the next call fails with 401.
- Every call appears on your Activity page.
Endpoints
Base URL: https://emailgents.com/api/public/v1. All responses are JSON except attachment downloads.
Connected mailboxes with status, sync window and coverage.
No parameters.
Folders per account with counts and sync state.
- account_id
- optional uuid
Unread counts and newest mail per mailbox.
- fresh
- true | false, default true
Search and list messages across mailboxes.
- q
- free-text query; quotes for phrases, - to exclude
- account_id
- repeatable
- folder
- repeatable role: inbox, sent, drafts, archive, trash, junk, all, starred, important, other
- folder_id
- uuid
- from, to
- substring match
- after, before
- ISO-8601
- unread, starred, has_attachments
- true | false
- limit
- 1–100, default 25
- offset
- integer, default 0
- order
- date | relevance
- fresh
- true | false, default true
One message with headers, body and attachment metadata.
- format
- text | html | both
- max_chars
- 500–400000
- body
- false to skip the body
The conversation containing a message, oldest first.
- bodies
- true to include bodies
- max_chars
- per-message cap, default 12000
Download one attachment (up to 25 MB) with its original content type.
No parameters.
Update flags on up to 100 messages. The only write.
- message_ids
- uuid[] in the JSON body
- read
- boolean
- starred
- boolean
Force a bounded sync of one mailbox now.
No parameters.
Responses
- Search responses carry total, hasMore, coverage, refresh, freshness and messages; read coverage.status before concluding that something does not exist.
- Message responses carry bodyInfo (source and nextOffset) and attachments with size and downloadable flags.
- Thread responses carry coverage so a partial thread is never presented as complete.
- Flag updates return per-message outcomes: updated, failed or not_found.
Errors
- HTTP status plus a JSON body: { error: { code, message, retryable, retry_after, target, next_step, correlation_id } }.
- 401 unauthenticated, 403 forbidden (key not scoped to that mailbox), 404 not_found, 400 invalid_input, 413 too_large, 502 provider_error, 504 provider_timeout, 503 server_unavailable.
- Messages never include credentials or raw provider payloads; quote the correlation_id when reporting a problem.
Limits
- Page size 1–100.
- Bodies capped by max_chars (default 60 000, maximum 400 000) with continuation offsets.
- Attachments up to 25 MB per download.
- Provider fetches are bounded per call; use fresh=false for the fastest indexed answer.
API questions
Can a key be limited to one mailbox?
Yes. Choose the mailboxes when creating the key; requests for any other account return 403 forbidden.
Can a key send mail?
No. There is no endpoint that sends, replies, moves or deletes. POST /messages only changes read and starred flags, and a read-only key cannot do even that.
Is there an SDK?
Not yet; the API is small enough to call with fetch or curl, and MCP covers agent frameworks directly.
Prefer MCP? MCP server reference.