Zapmail
Overview
API Reference
Overview
API Reference
  1. Capabilities
  • Introduction
  • Quickstart
  • Authentication
  • MCP
  • Versioning
  • Errors
  • Webhooks
  • Rate Limits
  • Pagination
  • Changelog
  • Capabilities
    • Mailboxes
    • Pre-Warmed
    • Deliverability
    • Domains
    • Export to Sequencer
    • Zapbox
    • Team Management
    • ZapShield
    • ZapCare
    • AI Insight
    • Deliverability Tests
    • ZapSites
    • Zapwarm
    • ZapPulse
  • Billing
    • Understanding Zapmail billing
    • Wallet
  1. Capabilities

Zapbox

Zapbox is the unified inbox for your Zapmail mailboxes. The public API exposes a fixed set of Zapbox operations as a proxy: your request is forwarded to Zapbox and the response is Zapbox's own JSON. Only the endpoints listed below are available. Any other path under /onebox returns 404 {"error":"Endpoint not found"}, and a wrong method returns 405 {"error":"Method not allowed"}.
Before you start: the account owner must have Zapbox consent enabled. Without it every call fails with 403, and consent cannot be set through this API.

Differences from the rest of the API#

Responses use Zapbox's own { "success": ... } JSON, not the standard status, message and data envelope. Errors use the standard error envelope.
Upstream validation failures arrive as 400, not 422.
Pagination is not the 10-item default of other Zapmail lists. connected-accounts and search-emails default to a limit of 50 (maximum 100), thread-emails to 100, and top-emails uses cursor pagination with no page.
workspaceIds (comma-separated) limits a search to those workspaces; IDs you do not have access to are dropped. It defaults to all your workspaces.

Allowed endpoints#

TaskEndpoint
List mailboxes available in ZapboxList Zapbox Connected Accounts
List threads (inbox view)List Zapbox Threads
Read all messages of one threadGet Zapbox Thread Messages
Search messagesSearch Zapbox Emails
Star, read, archive, move, label or trash messagesPOST /onebox/action
Send or schedule an emailSend Zapbox Email
Download an attachmentDownload Zapbox Attachment
Create a labelCreate Zapbox Label
Rename a labelRename Zapbox Label
Delete a labelDelete Zapbox Label

Read mail#

1
Find mailboxes
List Zapbox Connected Accounts returns the mailboxes available in Zapbox. Use the email addresses as the account value in the other calls.
2
List threads
List Zapbox Threads returns one entry per thread with its newest message. Pass the nextCursor of the previous response as cursor; it is null on the last page. Warm-up threads are excluded unless warmup is true.
3
Open a thread
Get Zapbox Thread Messages with threadId returns every message oldest first, with bodies and attachment metadata.
4
Download an attachment
Download Zapbox Attachment takes attachmentId, messageId, provider and account, which must be in the query string even though it is a POST. The response body is the raw file.
Search Zapbox Emails searches across mailboxes with free text and Gmail-style filters such as from, subject, dateWithin, isRead and hasAttachment. All filters combine with AND, and the response is a plain array with no total.

Send and act#

Send Zapbox Email sends from one of your connected mailboxes through its provider. Pass threadId and messageId to reply in a thread. With isScheduled true the email is sent at scheduledAt and the response is 202; a scheduled email cannot be cancelled through the API. Attachments cannot be sent through this API.
POST /onebox/action applies star, unstar, read, unread, archive, move, addLabel, removeLabel, trash, restore, unarchive, done or undone. Choose messages with threadMessages (thread ID to message IDs), or send an empty threadMessages with a filter that includes at least one of folder, accounts or before. Up to 5 threads are updated before the response (200). More than 5 threads, or any filter-based request, is queued and returns 202 with queued: true.

Labels#

Labels belong to the user and apply to every mailbox, so a name can exist only once. Create Zapbox Label returns 400 for a name that exists. Apply a label to messages with POST /onebox/action and action addLabel. Rename Zapbox Label and Delete Zapbox Label change the label for all your mailboxes but update messages only in the mailbox given as account, up to 10,000 messages per call. Deleting a label cannot be undone.
Related: Mailboxes, Webhooks.
Previous
Export to Sequencer
Next
Team Management
Built with