Introduction
What the Workwae API does, the concepts it is built on, and which guide covers each task.
Workwae is one API for the mailboxes your users connect: mail, calendar and contacts for Google and Microsoft 365 accounts, and mail for any IMAP/SMTP mailbox. Your backend calls a single REST API at https://api.workwae.com/v1, and Workwae syncs with each provider.
New here? The Quickstart goes from an API key to reading a connected mailbox in five steps.
Concepts
| Concept | What it is |
|---|---|
| Organization | Your Workwae workspace, called the tenant in the API. It owns the accounts, API keys, webhooks, settings and plan. Console members have the role owner, admin, member or viewer. |
| Account | One connected mailbox, identified by its id. Its provider is gmail, graph (Microsoft 365) or imap. Mail, calendar, contacts and sending are all addressed under /v1/accounts/{accountId}. Set externalRef to your own user id to find it again. |
| API key | A secret (wk_...) your backend sends as a bearer token. It holds scopes (read, write, send, admin) and reaches every account, or only the accounts you bind it to. |
| Account token | A short-lived token (wat_...) for one account, minted by your backend for a browser or other untrusted client. |
| Connect session | A Workwae-hosted page where a user signs in with Google or Microsoft, or enters IMAP settings. When they finish, an account exists and the browser returns to your app. |
| Event | A record of something that happened: an account connected, a message arrived, a send completed. Events reach you as signed webhooks and through the change feed. |
See Authentication and API keys for how keys, account tokens and MCP keys differ.
How an integration fits together
Create an API key in the console and keep it on your server.
Connect a user's mailbox with a connect session, or add mailboxes for a whole domain with an organization connection.
Read and change mail, calendar and contacts, and send mail, through the account's routes.
Follow changes through webhooks or the change feed instead of polling each mailbox.
Find a guide
| To | Read |
|---|---|
| Authenticate, choose scopes, rotate keys | Authentication and API keys |
| Call the API from TypeScript | TypeScript SDK |
| Handle errors, cursors, rate limits and retries | Errors, Pagination, Rate limits, Idempotency |
| Connect Google, Microsoft or IMAP mailboxes | Connect flows, IMAP and SMTP |
| Add every mailbox of a Google Workspace or Microsoft 365 domain | Organization connections |
| List, search and change messages | Reading mail |
| Send, schedule and track mail | Sending, Drafts, Mail merge, Tracking, Templates, Suppressions |
| Work with calendars, bookings and contacts | Calendar, Scheduling, Meetings, Contacts |
| React to new mail and other changes | Events, Webhooks, Change feed |
| Draft with AI or give agents mailbox tools | AI, MCP server |
| Export data and review activity | Exports, Audit log |
Every operation, with its parameters, scope and error reasons, is in the API reference.