Quickstart

From API key to first sent message.

Six steps with the TypeScript SDK: connect a mailbox, receive its events, then read and send mail.

Step 1

Get an API key.

Workspaces come with early access; once yours is open, create a key in the console at app.workwae.com and keep it in your secret manager, since it is shown once.

.env

# Your app's environment, not committed
WORKWAE_API_KEY=wk_...

Step 2

Install the SDK.

@workwae/sdk is a typed TypeScript client on npm, currently an alpha.

terminal

bun add @workwae/sdk
# or
npm install @workwae/sdk

Step 3

Create the client.

Pass the key from your own app’s environment; every method takes one object with its path, query and body fields.

workwae.ts

import { createClient } from "@workwae/sdk";

export const workwae = createClient({
  apiKey: process.env.WORKWAE_API_KEY,
});

Step 4

Connect a mailbox.

Create a hosted connect session and redirect the user to its URL; the browser returns with status and account_id in the query string.

connect.ts

const session = await workwae.connectSessions.create({
  redirectUri: "https://app.example.com/mail/connected",
  providers: ["google", "microsoft", "imap"],
  externalRef: "user_42",
});
// Redirect the browser to session.url

// Back on your redirect URI:
// ?status=success&account_id=6f1c2a4e-...

Step 5

Receive events.

Create a webhook endpoint, store its secret, and verify each delivery with parseWebhook before you trust it.

webhooks.ts

import { parseWebhook } from "@workwae/sdk";

const { endpoint, secret } = await workwae.webhooks.create({
  url: "https://app.example.com/hooks/workwae",
  filters: { eventTypes: ["message.created"] },
});

// In your handler: checks the signature and the timestamp
const body = await request.text();
const event = await parseWebhook(secret, request.headers, body);
if (event.known && event.type === "message.created") {
  console.log(event.data.message.subject);
}

Step 6

Read and send.

List the account’s messages, then reply from the same mailbox; sends are queued and retried, and results arrive as events.

mail.ts

const { items } = await workwae.messages.list({ accountId, unread: true });
const message = await workwae.messages.get({
  accountId,
  messageId: items[0].id,
});

await workwae.outbox.create({
  accountId,
  inReplyToMessageId: message.id,
  to: [{ address: "priya@example.com" }],
  subject: "Re: Q3 roadmap",
  text: "Thanks, I will review it today.",
});

Get a workspace and an API key.

We are onboarding a small number of teams. Tell us what you are building.

Request early access Read the docs

From API key to first sent message.

Get an API key.

Install the SDK.

Create the client.

Connect a mailbox.

Receive events.

Read and send.

Go deeper in the docs.

Quickstart guide

Connect flows

Webhooks

API reference

OpenAPI document

Get a workspace and an API key.