For developers

Build on Contextual

Every part of Contextual is meant to be programmable, through the same contract its own app uses: an API, a TypeScript SDK, an MCP server for AI agents, a command line and signed hooks. Whatever you build does only what a person ticks, for as long as they say.

Sign in, make an app, try its key on a made-up sample mailbox.

What you can build

Each part of Contextual, and the calls that drive it. Parts that open to keys next say Coming.

Today a key can drive every part: mail, line maps, search, people and the Record, bringing mail in, Exchange lines, Files and storage, each only as far as the person ticked.

1 of 8

Email: what needs the person, and drafts

Read Now as Contextual sees it: what the person was asked, what is due, what they wait on, each with who said it and the words that prove it.

Open a whole conversation with its topics pulled apart, list the people in it, and write reply drafts. A draft is only ever a draft: the person checks it and sends it.

TypeScript
const now = await cx.now();
for (const e of now.needsYou) console.log(e.title, e.due ?? "");
const thread = await cx.conversation(now.needsYou[0].conversationId);
const drafts = await cx.drafts("Robin");   // drafts only: nothing is sent
2 of 8

Line maps: a folder through time

Every folder has a line map: one line with a notch for each email, sent on one side and received on the other. Ask for it by person, topic or mark, a page at a time.

Exchange lines have a line map too, with each file's way of sharing, each opening and each note.

TypeScript
const [claim] = await cx.folders();
const line = await cx.folderLine(claim.id, { person: "rachel@northgate.example", limit: 50 });
// An Exchange line's map, too
const map = await cx.exchange.lineMap(lineId);
3 of 8

Bring in: what comes in, and when

Choose what comes in from a mailbox by labels, dates, senders or size, see about how much that is first, then start it now, at a time, or only at night.

Keep it at Google's actions (archive, label, mark read, each with Undo) come with it, under Tidy my mailbox. Connecting a mailbox and unsubscribing stay the person's own.

TypeScript
const [gmail] = await cx.ways();
const size = await cx.countWay(gmail.id, { after: "2024-01-01", labels: ["Claims"] });
await cx.setWayFilter(gmail.id, { after: "2024-01-01", labels: ["Claims"] });
await cx.wayJob(gmail.id, { action: "start", nightly: { from: "22:00", to: "06:00", offset: 0 } });
4 of 8

Exchange lines, both ways

Open a line between a firm and one client, invite them, ask for a document or send one, leave notes, and read the receipts for every step.

Each file keeps the way its sender chose: view once, view, keep a copy, or share with one person. Witness checks any copy against the sealed fingerprint. Each file's own A/B/C is carried and shown as chosen; the server enforcing it is coming.

TypeScript
const line = await cx.exchange.createLine({ subject: "14 Elmstead Avenue" });
const invite = await cx.exchange.invite({ lineId: line.id, name: "Sam", days: 7 });
await cx.exchange.ask(line.id, "Proof of funds");
await cx.exchange.note(line.id, "Viewing on Saturday at 11:00");
const receipts = await cx.exchange.receipts(line.id);
5 of 8

Files: every place a person keeps things

Search a person's computers, Google Drive and email attachments in one go, with the same magic words, and see every version of a file and what is kept twice.

Share a file on an Exchange line in the way the person picks, and start pairing a computer. Only the person approves a pairing, seeing the same four words on both screens.

TypeScript
const found = await cx.filesApp.search("kind:pdf quote kitchen");
const twice = await cx.filesApp.duplicates();
const file = found.groups[0].hits[0].item;
await cx.filesApp.share(file.id, { lineId, how: "view-once" });
7 of 8

The Record: asked, offered, agreed

The Record keeps what was asked, offered, agreed and due, each with the quote and the message that prove it. Read it to build a tracker, a report or a reminder.

Read the notes a person marked on their mail, confirmed or disputed. Only the person adds or changes them, from Contextual itself.

TypeScript
const { entries } = await cx.record();
const agreed = entries.filter((e) => e.kind === "agreed");
for (const e of agreed) console.log(e.title, e.proof[0]?.quote);
const notes = await cx.pills(messageId);
8 of 8

Storage: where it's kept, and taking it with you

See where a person's mail is kept, set a second copy on a drive, and export everything, sealed with their key, to bring back in elsewhere.

A key sees where it's kept and exports everything, sealed. The second copy and bringing an export back in stay the person's own.

TypeScript
const where = await cx.storage();
const sealed = await cx.exportEverything();   // sealed; keep sealed.code with the file

How you build

Six ways in, one set of permissions behind all of them.

1 of 6

One API, the one the app uses

Contextual's own screens use the same HTTP and JSON API your app does, so nothing is held back for us. The whole contract is one OpenAPI file.

A refusal says why in plain words, and names the permission it needed, so your app can ask the person for it.

Shell
curl https://email.contextual.exchange/v1/now \
  -H "Authorization: Bearer $CONTEXTUAL_KEY"
# The whole contract: GET /v1/openapi.json
2 of 6

The TypeScript SDK

One client, typed to the same shapes the app uses: Now, folders, line maps, conversations, search, the Record, Exchange lines and Files.

It has no dependencies and works wherever fetch does: Node, a browser, a worker.

TypeScript
import { Contextual, ContextualError } from "@contextual/sdk";

const cx = new Contextual({
  baseUrl: "https://email.contextual.exchange",
  token: process.env.CONTEXTUAL_KEY,
});
try { await cx.now(); }
catch (e) { if (e instanceof ContextualError) console.log(e.needs); }
3 of 6

An MCP server for AI agents

Give your own AI assistant Contextual's tools: what needs me, what was agreed, find conversations, file versions, draft replies, due dates and my permissions.

Each tool asks for its permission, like any app, and every use leaves a receipt. Drafts are drafts: nothing is sent.

Your assistant's settings
{ "mcpServers": { "contextual": { "command": "contextual-mcp",
  "args": ["--url", "https://app.contextual.exchange", "--read-only"] } } }
# Tools for every part: what_needs_me, search_mail, my_lines, open_line,
# files_search, ways_in, storage_info, my_permissions, …
4 of 6

A command line

Import .eml and .mbox files, bring mail in over IMAP, list what needs you, write drafts, make a calendar of what is due, export a case as a ZIP, or serve the whole app from a folder you choose.

Running a command is the permission to read the files you hand it, and the receipt says so.

Shell
contextual import claim.mbox --me robin@vale-home.example --store mail.db
contextual now --store mail.db --json
contextual export --store mail.db --out case.zip --name "Claim 4471"
contextual api lines        # over the API, with CONTEXTUAL_KEY
5 of 6

Signed hooks

Be told when something happens instead of asking. Each delivery is signed with your hook's own secret, with the time, so you can check it came from Contextual and is fresh.

Mail arriving, jobs, the Record, every step on an Exchange line, Files' places and pairings: each event goes only to apps allowed to know it, and is tried again for up to a day. Two events are coming: new mail filed into a folder, and a file's new version.

TypeScript, on your server
import { createHmac, timingSafeEqual } from "node:crypto";
// x-contextual-signature: t=<unix time>,v1=<HMAC-SHA256(secret, t + "." + body)>
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const want = createHmac("sha256", secret).update(`${t}.${body}`).digest();
const ok = timingSafeEqual(Buffer.from(v1, "hex"), want) && Date.now() / 1000 - Number(t) < 300;
6 of 6

Extensions: connectors, readers, actions

A connector brings mail in from somewhere new, a reader understands a kind of file, an action sends things out. Each says up front what it asks for, why, and for how long.

The person sees that list in plain words and ticks what to allow. Its code is pinned by fingerprint, so what runs is what was reviewed, and an update never widens what it may do.

manifest.json
{ "id": "com.example.receipts", "name": "Tidy Receipts", "version": "1.0.0",
  "publisher": "Example Ltd", "summary": "Files your receipts by shop.",
  "kinds": ["reader"],
  "asks": [{ "capability": "mail.read", "why": "To find your receipts" }],
  "maxDays": 30,
  "code": { "url": "https://example.com/receipts-1.0.0.js", "sha256": "<its SHA-256>" } }

Try it on made-up mail

Every app starts on a sample mailbox: made-up mail for Robin Vale, who is nobody real, with a lease renewal, a book club and a weekly veg box. Build and test against it with the same calls and the same ticks.

When it works, switch the app to your own account. It still does only what you ticked.

Pricing

The CLI, the API and the MCP server for your own use are part of the free core, always.

Pricing for apps you make for other people is Coming. There are no prices yet, and nothing is charged until it opens.

Want in early? Ask for the developer preview.