Overview

• Real money. 17 operations can charge the team’s wallet or saved card, and their descriptions say so. They are destructive, so cautious mode asks first.
• Nothing but a read is retried. InboxKit has no idempotency keys, and a purchase that timed out may still have gone through. The error says so: check domains.list or mailboxes.list before repeating one. An error handler in your app that asks for a retry can’t repeat it either: a retry of a call whose outcome is unclear gets the same error back with nothing sent. A new call goes through, so check first.
• Unexpected answers. If InboxKit’s answer doesn’t fit the documented shape, you get { parse_warning, raw } with the answer in raw. The call still happened, so don’t repeat it.
• Workspaces. Most operations act on one workspace. Pass workspaceId on the call or set inboxkit({ workspaceId }). With neither, a team with one workspace uses that one (found with one extra read per call), and a team with several gets an error naming them, even on a read.
• Live sending infrastructure. Changing a password or username, deleting or repairing DNS records, or running a resetup can stop a working mailbox. These are destructive too. Adding or editing a DNS record is write, as on our other DNS plugins, so check an MX change before you make it.
• Fields left out on purpose. workspaces.create takes no webhook URL, mailboxes.update no username and sequencers.add and sequencers.update no auto-export. InboxKit’s API has them, but each can send mailbox data elsewhere or change a live address. Use workspaces.updateWebhook and mailboxes.changeUsername, which need approval in cautious mode, and the dashboard for auto-export.
• Credentials. mailboxes.showCredentials and mailboxes.generateTotp return plaintext to whoever calls them. Corsair doesn’t log or store them, but your agent’s transcript may.
• Not covered: InboxKit’s unified inbox (reading and sending email, drafts, labels) and the team-level webhook URL. They are in InboxKit’s MCP server and dashboard but not its documented REST API. The dashboard’s Real-time email events switch isn’t handled yet either, because nothing documents those deliveries. Leave it off: each one would get a 404, and InboxKit pauses a URL after five failures in a row.

• 181 typed API operations
• 3 synced entities (domains, mailboxes, workspaces) for fast .search() / .list()
• 4 incoming webhook event types

​

Setup

npm install corsair @corsair-dev/inboxkit better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/inboxkit better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/inboxkit better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/inboxkit better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { inboxkit } from '@corsair-dev/inboxkit';

export const corsair = createCorsair({
	plugins: [
		inboxkit(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

inboxkit()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'inboxkit',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.inboxkit.api.domains.list({
	limit: 20,
	status: ['active'],
});

const tenant = corsair.withTenant('acme');
await tenant.inboxkit.api.dns.add({
	domain: 'example.com',
	records: [{
		host: 'www',
		type: 'CNAME',
		value: 'example.net',
		ttl: 3600,
	}],
});

​

Query synced data

const tenant = corsair.withTenant('acme');
const rows = await tenant.inboxkit.db.mailboxes.search({
	data: { status: 'active' },
	limit: 10,
});

​

Webhooks

inboxkit({
    webhookHooks: {
        mailboxes: {
            statusChanged: {
                after: async (ctx, result) => {
                    if (result.data?.data.mailbox.status === 'active') console.log('Ready:', result.data.data.mailbox.email);
                }
            },
        },
    },
})

​

What’s next