Glossary

The words behind the API.

39 terms from email, calendar and webhook integrations, each defined on its own terms and then tied to what Workwae does about it.

Admin consent

A Microsoft Entra administrator approving an app's permissions for a whole organization, so users are not asked one by one. Access with no signed-in user (app-only) always needs it. Workwae supports app-only access with admin consent in GCC High and DoD, through your own app registration or Workwae's where we run one.

App-only access

Calling an API as the application itself, with no signed-in user, using the OAuth client-credentials flow. On Microsoft Graph such a token cannot call /me, so a mailbox is addressed as /users/{mailbox}. In Workwae it is an organization connection.

At-least-once delivery

A promise that a message arrives one or more times, never silently zero. The receiver has to cope with duplicates, usually by remembering the ids it has handled. Workwae webhooks work this way: retries and replays deliver the same event id again, so handling should be idempotent on webhook-id.

Booking

One slot of a scheduling link taken by an invitee. Workwae re-checks the slot, creates the calendar event with the invitee as an attendee and sends booking.created; cancelling the booking deletes the event and sends booking.cancelled. The slot is claimed in the database before the event is created, so two bookings of the same account and start cannot both succeed.

Bounce

A failure notice from a mail server that could not deliver a message. It can come back at once or as a later message to the sender, and a permanent bounce means the address cannot receive mail. Workwae reports a later bounce as message.bounced, and permanent bounces go on the global suppression list.

Buffer

Free time kept before or after a bookable slot so meetings do not run back to back. A Workwae scheduling link has bufferBeforeMinutes and bufferAfterMinutes, 0 by default and up to 1,440; a slot is listed only when each account's own calendar is clear once the slot is widened by the buffers.

CalDAV

A standard (RFC 4791) for reading and writing calendars on a server over HTTP. It has no push, so clients poll. Workwae syncs CalDAV calendars for IMAP accounts once their settings name a CalDAV server, and polls the collections.

CardDAV

A standard (RFC 6352) for reading and writing contacts on a server over HTTP. Like CalDAV it has no push, so clients poll. Workwae syncs CardDAV contacts for IMAP accounts once their settings name a CardDAV server.

CASA

The Cloud Application Security Assessment: an independent security review that Google requires, on top of OAuth verification, of production apps that use restricted scopes such as Gmail's. Workwae's own Google app has not completed CASA; an app you register yourself needs its own assessment.

Change feed

An ordered log of every event, read by polling instead of receiving pushes. In Workwae, GET /v1/changes lists the tenant's events oldest first, paged with a cursor you store. It carries the same events and ids as webhooks and needs no public endpoint.

Cursor

An opaque token that marks a position in a list or stream, so the next request resumes there. Workwae lists answer a nextCursor; pass it back until it is null. The change feed's cursor is never null: an empty page means you are caught up, so keep the cursor and ask again later.

Delta query

A Microsoft Graph request that returns only what changed in a collection since the previous call, and a token for the next one. Workwae's Microsoft mail sync is messages/delta per folder and calendars use calendarView/delta. Message and folder delta is not available in the 21Vianet cloud, so those mailboxes connect over IMAP.

DKIM

DomainKeys Identified Mail. The sending domain signs each message with a private key, and receivers check the signature against a public key published in DNS. It shows the message was signed by that domain and not altered in transit. Workwae sends through the account's own provider (Gmail, Microsoft 365 or its SMTP server), so signing is set up on the mailbox's domain with that provider, not with Workwae.

DMARC

A policy a domain publishes in DNS saying what receivers should do with mail that fails SPF and DKIM checks aligned with the visible From domain (nothing, quarantine or reject), and where to send reports. It is configured on the mailbox's domain, not in Workwae, which sends through the account's own provider.

DoD

The Microsoft 365 environment for the US Department of Defense. It has its own sign-in (login.microsoftonline.us) and Graph host (dod-graph.microsoft.us), and a token from another cloud is not valid in it, so it needs its own app registration. Workwae connects DoD accounts and calls dod-graph.microsoft.us for them.

Find a time

Asking when several people are all free in a range and getting suggested slots back; nothing is booked. In Workwae, POST /v1/accounts/{accountId}/availability/find reads the busy times of up to 20 attendees over up to 62 days, and POST /v1/availability/find finds slots across several accounts where all of them, or any of them, are free. A scheduling link stores the same question and adds booking.

Free/busy

Whether a person is free or occupied over a time range, without any event details. Workwae reads it from the provider for up to 20 attendees in one request and reports each block as busy, tentative, oof, working_elsewhere (which does not block a slot) or unknown; Google reports every block as busy. Free/busy is the raw input; find a time turns it into suggested slots.

GCC High

Microsoft 365 US Government Community Cloud High, a separate cloud with its own sign-in host (login.microsoftonline.us) and Graph host (graph.microsoft.us). Tokens do not cross clouds, so an integration needs an app registered in that cloud. Workwae connects GCC High, DoD and GCC accounts beside worldwide ones; GCC itself uses the worldwide endpoints.

Gmail watch

users.watch registers a mailbox to publish change notifications to a Google Cloud Pub/Sub topic. A watch lasts at most 7 days, so it has to be renewed; Google recommends daily. The notification carries a history id, not the changed messages. Workwae renews watches daily and polls an account when Google refuses the watch.

Graph subscription

A registration with Microsoft Graph to receive change notifications for a resource such as me/messages. Creating one requires answering a validation handshake, and it expires: a message subscription lasts at most 10,080 minutes and has to be renewed before then. Workwae keeps subscriptions for mail and calendars and renews them at half their lifetime.

History ID

Gmail's marker for a point in a mailbox's change history. A push notification carries the mailbox's current history id; calling users.history.list with the last id you processed returns what changed since. If that id is too old Google answers 404 and a full resync is needed. Workwae replays history.list and, on a 404, re-reads the mailbox and diffs it against its index.

Idempotency key

A unique value a client sends with a request so that retrying it cannot run it twice. Send an Idempotency-Key header on any authenticated POST to the Workwae API: a retry with the same key and request gets the first answer back, marked Idempotent-Replayed: true, for 24 hours. It protects your calls to Workwae; deduplicating Workwae's deliveries to you uses webhook-id.

IMAP IDLE

An IMAP extension (RFC 2177) in which the client keeps a connection open and the server announces changes to a mailbox as they happen. It works per mailbox and per connection; it is not a webhook. Where a server supports IDLE, NOTIFY or both, Workwae listens; otherwise it polls, and your app receives signed webhooks either way.

Lifecycle notification

A Microsoft Graph message about a subscription itself, sent to its lifecycleNotificationUrl. reauthorizationRequired asks you to renew or refresh the subscription's authorization, subscriptionRemoved says it is gone and must be recreated, and missed says some notifications were not delivered. Handling them keeps a subscription alive.

MCP

The Model Context Protocol, an open protocol that lets AI clients such as chat assistants and coding agents discover and call tools on a server. Workwae runs an MCP server at https://api.workwae.com/mcp; its tools search and read mail, calendars and contacts, save drafts, and send only with the send scope.

Message-ID

The header that gives each email a unique identifier. A reply's In-Reply-To holds its parent's Message-ID and References lists the thread's ancestors, which is how mail clients rebuild threads; Gmail also threads by threadId. Workwae gives each send a Message-ID of the form <outbox-id@sender-domain>, and if a provider replaces it, sync links the Sent copy through an X-Workwae-Outbox header.

Minimum notice

How far ahead a slot must start to be offered, so nobody is booked into the next few minutes. In Workwae it is minimumNoticeMinutes on a scheduling link, 0 by default and up to 86,400 (60 days); earlier slots are not listed.

OAuth scope

A permission an app asks for in an OAuth consent, such as Mail.ReadWrite on Microsoft or gmail.modify on Google. Users can untick scopes on Google's consent screen, so an app has to check what was actually granted. Workwae asks for the least it needs and checks the scopes granted.

Outbox

In Workwae, an account's queue of outgoing messages. A send returns 201 at once with an outbox entry; the account's provider (Gmail, Microsoft 365 or its SMTP server) sends it in the background, and send.sent, send.retrying and send.failed events report each step. An entry can be scheduled, or undone before it goes.

Refresh token

A long-lived OAuth credential that gets new access tokens without the user signing in again. It belongs to the OAuth app that issued it, so whoever holds the same app's refresh tokens can keep users connected. Workwae can import refresh tokens your own app issued, which is how a migration avoids asking users to consent again.

Replay

Resending an event that was already produced. In Workwae you can replay one event, or up to 1,000 from a time range per call; a replay keeps the original id and body with a fresh signature, so handling keyed on webhook-id stays safe. The same word names an attack, replaying a captured request, which receivers reject by checking the signed timestamp.

Restricted scope

A Google OAuth scope that exposes sensitive user data, such as the content of Gmail messages. A production app using one must pass Google's verification and a security assessment (CASA). Workwae's own Google app requests gmail.modify rather than the full https://mail.google.com/ scope, so permanent delete is refused for those accounts and trash works.

Round-robin

Spreading bookings across a team by offering a slot when at least one member is free and giving it to one of them. A Workwae scheduling link with mode: "any" does this: the booking goes to the free account with the fewest bookings of that link in the last 30 days, counting any status, and ties go to the earliest in accountIds. With mode: "all", the default, a slot needs every account free, and the booking is one event on the first account that invites the others.

RSVP

A reply to a calendar invitation: accepted, declined or tentative, optionally with a comment. In Workwae you answer one occurrence or the whole series, and choose whether to tell the organizer. An organizer cannot answer its own meeting, and on Google only the account's own attendee entry changes.

Scheduling link

A stored booking configuration: which accounts can be booked, for how long and when, with working hours in a time zone, slot length and step, buffers, minimum notice, a daily cap and how many days ahead to offer. You list its open slots, show them to an invitee and book one, and Workwae creates the calendar event; the booking page itself is yours to render.

Signed webhook

A webhook request that carries a signature, so the receiver can confirm who sent it and that the body was not altered. Workwae follows Standard Webhooks: HMAC-SHA256 over the id, timestamp and body, in the webhook-id, webhook-timestamp and webhook-signature headers. Verify the raw body exactly as received; the SDK's parseWebhook does and allows five minutes of clock tolerance. After a secret rotation the old secret keeps signing for a grace period.

SPF

Sender Policy Framework. A DNS record lists the servers allowed to send mail for a domain, and receivers check the sending server against it. Together with DKIM it feeds DMARC. Workwae sends through the account's own provider, so the record belongs to the mailbox's domain, not to Workwae.

Suppression list

A list of addresses that bulk mail must skip: people who unsubscribed, bounced or opted out. In Workwae a send or mail merge names a list with listId; unsubscribes always suppress, permanent bounces go on a global list, and an address on the named list or the global one is skipped with reason suppressed.

Early access

Skip the provider plumbing.

Workwae is in early access; tell us what you are building, or read the docs first.