IMAP and SMTP

Connect with a password

Any mailbox that speaks IMAP (and SMTP for sending) can be connected with its address and password. The login is checked against the servers before anything is stored, so a created account is one that worked.

curl -X POST "https://api.workwae.com/v1/imap-accounts" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "email": "[email protected]",
  "password": "app-password",
  "externalRef": "user_42"
}'

With dav, the account syncs calendars and address books as well as mail, and the halves found switch calendarEnabled and contactsEnabled on unless settings names them. 400 dav_discovery_failed means neither a CalDAV nor a CardDAV server was found or answered. Without dav, an IMAP account syncs mail only.

A CalDAV server without scheduling (RFC 6638) tells no attendee about a change, so workwae mails invitations, updates, cancellations and replies from the account's SMTP server. It does so only for a meeting the account organizes, and only to the attendees it has indexed or the request names. Writing with notify on is refused with 400 unsupported when the account has no SMTP server; a mail that fails after the event was written is logged, and the write stands.

Autodiscovery

To prefill your own settings form, look the servers up first. GET /v1/autoconfig answers 422 autodiscovery_failed when nothing was found, which is the cue to ask the user for the servers.

curl "https://api.workwae.com/v1/autoconfig?email=ada%40example.com" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

{
  "source": "autoconfig",
  "imap": { "host": "imap.example.com", "port": 993, "security": "tls", "user": "[email protected]" },
  "smtp": { "host": "smtp.example.com", "port": 465, "security": "tls", "user": "[email protected]" },
  "oauth": null,
  "dav": {
    "source": "well-known",
    "calendarUrl": "https://dav.example.com/",
    "contactsUrl": "https://dav.example.com/"
  }
}

• source says where the settings came from: provider, autoconfig, ispdb, srv or mx.
• oauth names the provider (google or microsoft) whose sign-in reaches this mailbox. Prefer an OAuth connect flow over a password for that mailbox.
• dav holds the CalDAV and CardDAV URLs when a source names them, or null. Pass them on as the account's dav settings; creating the account resolves them to the user's calendars and address books.

Change servers or password

PATCH /v1/accounts/{accountId}/imap replaces the fields it is given and checks the result like a new account. An account in reauth_required (after a password change, for example) becomes active again.

curl -X PATCH "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/imap-settings" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "password": "new-app-password" }'

IMAP with OAuth (XOAUTH2)

Google and Microsoft mailboxes can also be read over IMAP and SMTP, authenticated with an OAuth grant instead of a password. Pass "mailAccess": "imap" in the options of a hosted session or a headless OAuth start; the sign-in creates an IMAP account. The grant then carries mail scopes only, and the account has no calendar.

Google needs your own Google OAuth app for it (oauthAppId, or oauthAppIds.google on a session): the workwae platform app connects Gmail through the Gmail API only, and an IMAP start through it is refused with google_imap_requires_own_app. Microsoft works with either app.

curl -X POST "https://api.workwae.com/v1/oauth-authorizations" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "provider": "google",
  "oauthAppId": "<your Google OAuth app id>",
  "redirectUri": "https://app.example.com/mail/connected",
  "options": { "mailAccess": "imap" }
}'

A reconnect of such an account keeps its mail access.

The hosted IMAP form

Include imap in a hosted session's providers and the connect page offers an IMAP/SMTP form next to the Google and Microsoft buttons. It looks up the servers, checks the login and creates the account, then sends the browser to your redirect URI like the OAuth flows do. The page calls the API with the session token only, never your API key, and each session is rate limited on its own.

curl -X POST "https://api.workwae.com/v1/connect-sessions" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "redirectUri": "https://app.example.com/mail/connected",
  "providers": ["imap"]
}'