Unipile compatibility

What matches Unipile’s API v2, and what’s different.

The API follows the shapes of Unipile’s API v2: ids, lists, the auth intent, webhook endpoints and event names. Code written for Unipile v2 needs few changes. The engine’s own version is v1, so every path starts with /api/v1.

The same

Authentication	A DSN and an access token, sent in the X-API-KEY header
Ids	A type prefix on every id: acc_…, email_…, att_…, fld_…, we_…, evt_…, pk_…
Lists	{ "object", "data", "has_more" }. Offset paging with offset and limit; cursor for long lists
Connecting accounts	POST /auth/intent with provider: "imap", the address and password, state, and account_id to reconnect. See Connect a mailbox
Accounts	GET, PATCH (metadata) and DELETE /accounts/{id}. status is running, errored or disconnected; is_locked, initial_sync, user_id, provider
Webhook endpoints	/webhooks/endpoints with url, trigger_events, account_ids, description, headers, enabled; /webhooks/conversations for the delivery log
Event envelope	{ "object": "Event", "id", "type", "created_at", "account_id", "endpoint_id", "data" }
Event names	email.new, email.new.bounce, email.delete, email.draft.new, email.draft.delete, email.folder.*, tracking.open, tracking.click, account.add, account.reconnect, account.remove, account.status.*
API keys	/api-keys, with the key shown once

Different

	Unipile v2	Email engine
Base path	/api/v2	/api/v1
Connection page	A page run by Unipile where your users connect their mailbox	Not offered. Connect mailboxes with POST /auth/intent from your own app, or in the dashboard
Email endpoints	None	Ours: /emails, /emails/{id}, attachments, /drafts, /folders, /contacts. They use the v2 conventions for ids and lists
Extra event		email.update (read, starred, moved, trashed). Unipile v2 has no email update event
Webhook signature		X-Email-Engine-Signature (HMAC-SHA256 with the endpoint’s secret). See Verify signatures
API key scopes	Scopes per key	No scopes: every key has full access (role: "service")
Hosting	Unipile’s cloud	One workspace per customer, with its own server and database
Channels	Email, LinkedIn, WhatsApp and more	Email only: IMAP (imap, Gmail included, with an app password). Google and Microsoft sign-in aren’t offered yet
Where mail lives	Read from the provider	Synced into your workspace’s database, so lists and search are fast. Attachments are copied to your storage
Initial sync	initial_sync_enable (IMAP only), initial_sync on the account, account.initial_sync.* events	The same fields and events, for IMAP, plus initial_sync_days (1 to 30, at most 30). Off by default: only mail from the moment the account connects. See Initial sync
Errors		status, type, title, detail. See Errors

Moving from Unipile

1. Replace your Unipile DSN and access token with your workspace’s (see Quickstart), and use /api/v1 in your paths.
2. Create your webhook endpoints again, and check the X-Email-Engine-Signature header with the new secret.
3. Have users connect their mailboxes again through your app with the auth intent: credentials can’t be moved between services.