Your app connects mailboxes, calendars and contact books, and gets every change back as a signed webhook or from an ordered feed. Mail you send goes through a queue.
Three paths run through Workwae: connecting an account, syncing and delivering changes, and sending mail. Pick a step or a node to trace it. Moving dots show direction.
Your backend calls POST /v1/connect-sessions with an API key and gets a link that
works once, for 60 seconds to 24 hours (one hour by default). Headless OAuth does the same from
your own provider picker.
The hosted page offers Google, Microsoft 365 and an IMAP and SMTP form. For Google and Microsoft, sign-in and consent happen at the provider, so Workwae never sees the password. Workwae seals the credentials, creates the account and returns the user to your allowlisted redirect URI with its id.
Each account is read from its provider by cursor: Gmail history ids, Microsoft Graph delta
queries, IMAP UIDs, CalDAV and CardDAV sync tokens. A provider push only wakes the sync, and
polling is the backstop. Failures back off from 30 seconds to 15 minutes; a revoked grant sets
reauth_required.
A change, a send or an account lifecycle step becomes one event with a stable id. The log keeps
events for eventRetentionDays: 14 days by default, 7 to 30.
Matching events are POSTed to your HTTPS endpoint, signed with Standard Webhooks (HMAC-SHA256). Answer 2xx within 10 seconds. A failed delivery retries after 5 seconds, doubling up to an hour, and is given up after 3 days; an endpoint with 72 hours of failures is disabled. The delivery log and replay recover missed events.
GET /v1/changes returns the same events with the same ids, oldest first, 1 to 200
per page. Store nextCursor, which is never null; an empty page means you are
caught up.
POST /v1/accounts/{accountId}/outbox queues an entry and answers 201. The
account's provider (Gmail API, Microsoft Graph or SMTP) sends it in the background: queued,
sending, then sent, failed or cancelled, with an undo window of up to 60 seconds. The result
returns as send.sent, send.retrying or send.failed
through steps 4 to 6.
A scheduling link lists open slots computed from its accounts' connected calendars, using your
hours, buffers and notice. Booking a slot creates the calendar event, with a meeting link if
you ask for one, and sends booking.created. See
bookings.
Servers use an API key (wk_) with the scopes read, write, send and admin, which
can be limited to some accounts. Browsers get an account token (wat_) that your
backend mints with a write-scope key: it reaches one account's routes for 60 seconds to 24
hours, 15 minutes by default.
Each point below is how the API and the delivery pipeline behave today, with a link to the guide that specifies it.
For Google and Microsoft, the user signs in and consents at the provider; the browser returns only to a redirect URI on your allowlist. IMAP mailboxes use a form on the hosted page, and plaintext IMAP and SMTP logins are refused. Credentials are sealed before they are stored.
Workwae keeps an index and sealed credentials. Message bodies are read from the provider on request, or stored only if you choose body storage. A provider push is a wake-up: the sync re-reads from the provider rather than trusting the notice.
Events have a stable id and are kept for 7 to 30 days (14 by default). Webhooks and the change feed carry the same body and the same id, so one dedupe table covers both. A new account announces itself once with account.initialized when its first sync finishes.
Deliveries are signed with Standard Webhooks. A failed delivery retries from 5 seconds, doubling to an hour, until 3 days after it was queued. An endpoint with 72 hours of failures is disabled, and the delivery log, replay of one event, a range or failed deliveries, and test events help you recover.
GET /v1/changes lists events oldest first. Save nextCursor after each page and resume from it after any downtime, as long as you poll within the retention period. It needs no public endpoint.
The outbox entry is stored and acknowledged with 201 before any provider call. You can reschedule or cancel it until it starts sending. Delivery is at least once, and an unknown outcome, such as a lost reply from the server, is reported as outcome_unknown instead of being sent twice.
A scheduling link serves open slots computed from its accounts' connected calendars. Booking re-checks the slot, creates the event with the invitee as an attendee and sends booking.created through the same event path.
An API key can read and change every mailbox it reaches, so it belongs on your server. For a browser, your backend mints an account token that reaches one account for at most 24 hours, and then expires without any cleanup.
Workwae is in early access; tell us which providers your users are on, and read the quickstart in the meantime.