Documentation

Tinbox docs

Guides for getting Tinbox running on your own Cloudflare account, plus a complete typed reference for the agent tools, CLI, and SDK.

New here? The extend & automate decision map shows which surface to reach for — skills, the assistant, autopilot, agents, or a plugin.

89 tools · 114 CLI commands · 72 SDK methods · 12 skills

Quickstart

Scaffold a self-contained deployment, then point it at your domain. Pick your package manager:

npmpnpmyarnbun

npx tinbox init acme.dev
cd tinbox-acme
npm install

pnpm dlx tinbox init acme.dev
cd tinbox-acme
pnpm install

yarn dlx tinbox init acme.dev
cd tinbox-acme
yarn install

bunx tinbox init acme.dev
cd tinbox-acme
bun install

Guides

Fresh deploy — init to first sign-in

Scaffold a Tinbox project with one command, deploy it to your own Cloudflare account, and sign in for the first time — the whole path from empty folder to a working inbox.

Connect your domain — DNS, routing, verification

Point your own domain at the deployment — attach it, turn on inbound Email Routing, add the SPF/DKIM/DMARC records, and watch verification flip live in Settings → Domains.

Your first campaign — audience, import, compose, send

Send your first broadcast — create an audience, import or paste in your list, compose the email, test it, then approve and fan out. Both the guided in-app flow and the CLI path.

Cold outreach setup — SMTP, cold domains, review queue

Set up cold outreach the right way — a bring-your-own SMTP provider on an isolated cold subdomain, then source, draft, review, and launch a campaign behind a human approval gate.

Connect Claude and agents — chat, MCP, CLI

Put an agent to work on your inbox — the in-app assistant, Claude Desktop or Claude Code over MCP, and the tinbox CLI for headless agents. All three ride one shared, allowlist-scoped tool manifest.

Install Tinbox

Scaffold a new Tinbox deployment with one command and run it locally.

Deploy to your Cloudflare account

Two ways to put Tinbox on your own Cloudflare account — the one-click button or the local tinbox CLI — plus the dashboard and command steps for everything the deploy can't finish for you.

Updating Tinbox

How to update your Tinbox deployment to a newer version.

Connect an MCP client

Let Claude or any MCP agent drive your inbox with the same tools the in-app assistant uses.

Core Concepts

The mental model behind Tinbox, from inboxes and threads to the git archive, audiences, campaigns, the send ledger, capability tokens, and the agent-first design.

Send Transactional Email

Send transactional email from your other apps with the Tinbox SDK, a Resend-compatible client running on your own Cloudflare account.

Switch Email SDKs

Keep your existing Resend, SendGrid, Mailjet, Postmark, or Mailgun SDK while moving transactional sending to Tinbox, with a full provider compatibility matrix.

Switch from Resend

Replace Resend's transactional API with Tinbox, including the exact project edits, Resend SDK base URL option, field mapping, and compatibility limits.

Switch from SendGrid

Replace SendGrid's transactional Mail Send API with Tinbox while keeping @sendgrid/mail for simple sends.

Switch from Mailjet

Replace Mailjet's transactional send API with Tinbox while keeping node-mailjet for v3.1 Messages sends.

Switch from Postmark

Replace Postmark's transactional Email API with Tinbox while keeping the postmark ServerClient for sendEmail and sendEmailBatch.

Switch from Mailgun

Replace Mailgun's basic messages.create transactional send path with Tinbox while keeping mailgun.js where it fits.

Send a Newsletter

Build an audience, author a campaign, review and approve it, then fan out an idempotent newsletter with one-click unsubscribe, all on your own Cloudflare account.

The four AI surfaces in Tinbox — the interactive assistant, autopilot, dedicated agents, and agentic skills — plus how the assistant drives your inbox over chat, MCP, and the CLI through one shared tool manifest.

Give your agent an email

Give an AI agent a real address on your domain, so it can be contacted, register for services, follow up with people, draft replies, and work in the world under your review.

Build a drip / onboarding automation

Run a triggered, multi-step email sequence — onboarding new signups, a beta-wave invite with an automatic follow-up when no action is taken — on a per-person clock, from your own Cloudflare account.

Retrieve mail and attachments

Search live Tinbox mail, read complete threads, download attachments safely, inspect inbound source, or take a full account archive.

Import Existing Mail & Lists

Choose the right local-first path for Gmail, password-authenticated IMAP, mbox, Mailchimp, or a Tinbox account archive.

Download all your Tinbox data

Create, protect, verify, and restore a portable Tinbox archive containing selected D1 rows plus retained raw messages and attachments.

Run outreach with an external agent

Drive a full cold-outreach run — create, source, draft, review, approve, launch, read replies — from an external agent over MCP or the CLI, using the same campaign tools the in-app assistant has.

Cold outreach in one message

Ask the in-app assistant to run a cold-outreach campaign in a single message — it checks readiness, creates the campaign, sources prospects, drafts per-recipient bodies, and hands you a review queue. You approve; the assistant never sends.

Writing a skill

The defineSkill API end to end — the reversible-only contract, the SkillContext shape, a copyable handler, evals, and how to cause a side effect.

Consume Tinbox from your own repo

Wire the tinbox package into a sibling repo before npm publish — the file: dep form, build-first, the exports subpaths, the zod-4 peer, and exactly what init/setup write.

Route sending lanes to your own provider

Point the transactional, lists, or outreach lane at Amazon SES or an SMTP relay — profile fields, where credentials go, how failures surface, and how to verify with doctor.

Run Tinbox inside a monorepo

Where a Tinbox instance lives in a monorepo (one app folder), how to isolate its lockfile so the cross-repo dep never leaks into CI, and the exact files, scripts, and deploy loop — modelled on a real tenant.

Source access and the public bundle

What is public, what a lifetime license adds, and how paid readable-source access is granted without adding runtime phone-home or feature gates.

Set up cold-outreach SMTP

Wire the BYO SMTP provider that carries your cold outreach — which providers work, how to create credentials, per-domain bindings, and the in-app test send.

Stage Cloudflare Email delivery events

Prepare Tinbox's default-off Cloudflare Email Sending lifecycle Queue, DLQ, and trust allowlists locally without creating a subscription or enabling the feature.

Extend Tinbox — the six building lanes

The six ways to build on Tinbox — Parsers, Replies, Scripts, Plugins, Views, Agents — with a decision table so you can answer "which lane do I use for X?" in one page.

Extend: Parsers — read, classify, and render inbound mail

Lane 1 of Extend Tinbox — reactive skills that classify inbound mail and render a card, plus the in-app skill-draft playground.

Extend: Replies — reply rules, auto-responses, and drip follow-ups

Lane 2 of Extend Tinbox — the three scopes of reply logic, from org-wide Handbook policy to per-send thread directives, on one autonomy dial.

Extend: Scripts — ad-hoc mailers, syncs, and imports

Lane 3 of Extend Tinbox — the programmatic surface (SDK, CLI, MCP) on one token, including named-template render on send.

Extend: Plugins — routes, crons, mail hooks, and private tables

Lane 4 of Extend Tinbox — in-worker modules with definePlugin: HTTP routes, cron handlers, inbound/outbound mail hooks, namespaced D1 tables, and scoped secrets.

Extend: Views — dashboard tiles, cards, and agent tools

Lane 5 of Extend Tinbox — config-registered UI surfaces (plugin.ui slots) plus tenant-authored agent tools (plugin.agentTools), both deploy-time and declarative.

Extend: Agents — sourcing and campaign agents

Lane 6 of Extend Tinbox — agents that source people and run outreach, built on agentic skills over the outreach seam.

Open detection for inbox email

Tinbox can add a tiny remote image to future HTML messages composed by people in an inbox. When an email client requests that image, Tinbox shows Open detected on the sent message. This is a useful hint, not proof that a person read the message.

Roll your own emails, in minutes.

Inbox, sending, and lists — one deployment you own, programmable with Skills and run with agents. Self-hosted, yours to keep.

Deploy to Cloudflare Star on GitHub