Skip to content
Tinbox
Sign in

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.

An agent gets much more useful when it has an address.

Without email, an agent is trapped inside a chat box. It can think, draft, and answer questions, but the outside world has nowhere to reach it. Give it a real mailbox on your domain and it becomes a working identity: people can reply to it, services can send it confirmations, venues can answer its pitch, forms can send receipts, and every thread becomes context it can pick up later.

That is the shift: not "AI writes email," but your agent can be reached.

support-bot@yourdomain.com can triage customer mail. press@yourdomain.com can collect inbound media requests. bookings@yourdomain.com can contact venues, track replies, and draft next steps. rights@yourdomain.com can submit your book to agents, publishers, newsletters, and festivals, then keep the entire conversation in one owned archive.

Tinbox makes that identity useful without making it reckless. The agent reads and drafts through the same inbox state humans see. It gets a scoped token, not a master key. It monitors with a live freshness probe. It drafts before it sends. And the send ledger makes retries safe when you do grant authority.

This is the agent identity layer in Tinbox.

Tinbox already has the assistant, MCP, skills, autopilot, and dedicated agents. This guide is about something more basic and more powerful: giving the agent a reachable address it can use outside Tinbox. The address is not a generic vendor handle. It is @yourdomain.com, backed by your inbox, your archive, your permissions, and your sending domain.

What this unlocks

A mailbox gives the agent a place in the world. Once it has one, it can:

  • Represent a role. support-bot@, sales-research@, bookings@, licensing@, studio-assistant@, founder-office@.
  • Receive replies. A venue, customer, journalist, agent, or partner can answer the agent directly, and the thread stays attached to the work.
  • Register for services. The agent can sign up for tools, directories, portals, trials, newsletters, and marketplaces that verify by email.
  • Submit forms. Contact forms, demo requests, partnership forms, grant applications, festival submissions, supplier portals, job boards.
  • Run outbound work. Draft pitches, follow-ups, reminders, status checks, quote requests, booking requests, invoice nudges, and intro emails.
  • Keep memory in the inbox. Confirmations, receipts, rejections, warm replies, attachments, and decisions become searchable context.
  • Escalate cleanly. When the agent is uncertain, it asks the operator or leaves a draft for review instead of improvising.

For artists, that might be an agent that contacts venues, tracks availability, follows up with promoters, and drafts replies for the human to approve. For an author, it might submit a book to literary agents, newsletters, festivals, and podcasts, then summarize who replied and what each person needs next. For a small business, it might own vendors@, register for supplier portals, collect quotes, and keep procurement conversations moving.

The address is the handle. The inbox is the memory. The token is the boundary.

Why owned identity matters

An agent identity product can give your agent a mailbox, a handle, and a place to receive confirmations. Tinbox's version does that inside the infrastructure you own:

Generic hosted identityTinbox agent email
The agent gets a vendor-hosted addressThe agent gets an address on your domain
Mail history lives in a shared serviceMail lives in your tenant D1/R2 and optional git archive
Permissions are product settings in someone else's appPermissions are Tinbox grants and scoped tokens
Sending authority depends on the providerSending uses your sending domain and Tinbox's ledger
Custom workflow means another integrationCustom workflow can run as a Tinbox skill, action, or plugin

That matters when the agent is doing real work. If bookings@studio.com is negotiating with venues, those threads should become part of the studio's owned record. If rights@author.com is corresponding with literary agents, the author should keep the archive and credentials. If vendors@shop.com is registering for portals and collecting quotes, those confirmations should land in the company's mail stack, not a separate agent vendor account.

The goal is not to make agents feel magical. It is to make them legible, reachable, accountable, and useful.

Agent identity patterns

Use the mailbox as the stable identity, then attach the behavior you want:

PatternThe agent does
Artist booking agentFinds venue contacts, drafts booking pitches, tracks availability, prepares follow-ups
Author submissions agentContacts literary agents, podcasts, newsletters, festivals, and rights desks
Sales research agentRegisters for directories, requests demos, follows up with prospects, summarizes replies
Vendor desk agentRegisters for supplier portals, collects quotes, tracks invoices and onboarding forms
Press assistantReceives media requests, drafts responses, collects assets, tracks deadlines
Founder office agentHandles intros, scheduling threads, investor follow-ups, and relationship notes

Each pattern can start read-only. Then it can draft. Then, for narrow cases, it can send. The identity stays stable while the authority grows carefully.

The safe shape

The setup has three pieces:

  1. Create a real inbox address for the agent.
  2. Mint the smallest useful scoped token.
  3. Teach the agent the mail-check loop.
  4. Keep sends, campaigns, imports, and routing changes human-gated until you deliberately grant more authority.

Choose the identity

Pick the address based on how the outside world should understand the agent:

AddressGood for
support-bot@acme.comA visible support assistant that can receive customer replies
founder-office@acme.comA founder's research, scheduling, and follow-up helper
bookings@studio.comVenue outreach, event pitches, availability, and confirmations
rights@author.comLiterary agents, publishers, festivals, podcasts, permissions
vendors@shop.comSupplier quotes, portal registrations, invoices, procurement
research@acme.comMarket research, directory signups, analyst requests, sourcing

Use a dedicated agent address when people should know the agent is a reachable identity. Use a shared human address like support@ when the agent is helping behind the scenes.

1. Create the mailbox address

Create the address on your own domain:

tinbox create-inbox --local-part support-bot --type shared --json

You can also ask the in-app assistant:

Create a shared inbox called Support Bot at support-bot@acme.com.

Inbox creation is an org-admin action. In chat, Tinbox shows an approval card with the exact address and type before creating it. In the app, the same concept lives under Settings -> Inboxes.

2. Mint the smallest useful token

Give the agent an inbox-scoped token, not an org-wide key:

tinbox tokens create --inbox support-bot --role viewer --ttl 30d --json

Start with viewer when the agent should only read and summarize. Move to agent when it should draft replies:

tinbox tokens create --inbox support-bot --role agent --ttl 30d --json

The token is shown once. Store it in the agent runtime as TINBOX_TOKEN, with the deployment URL as TINBOX_API_URL:

export TINBOX_API_URL=https://mail.acme.com
export TINBOX_TOKEN=tbx_...
tinbox whoami --json

whoami should return the inboxes the token can access. If it exits 2, the token is missing, invalid, or expired.

The token is the difference between identity and overreach. A literary-submission agent does not need admin rights. A bookings agent does not need campaign send. A support draft agent may not need send rights at all. Start narrow, watch how the work behaves, then widen only where the workflow earns it.

3. Teach the agent the mail loop

Paste this into the agent's project instructions:

You are the mailbox agent for support-bot@acme.com.

Your job is to operate this address as a real working identity. You may receive
mail, search prior conversations, draft replies, and keep track of follow-ups.
You represent the operator, but you do not pretend to be human.

Use the tinbox CLI with --json. Parse stdout as JSON and branch on exit codes.
You may read threads and draft replies. Do not send unless the operator
explicitly asks you to send.

Start every session with:
tinbox whoami --json

Find work with:
tinbox threads --unanswered --inbox support-bot --json

Before drafting, read the full conversation:
tinbox thread <threadId> --json

Draft replies instead of sending:
tinbox draft create --thread <threadId> --text "..." --json

Before editing a draft, probe its version:
tinbox draft version <draftId> --json
tinbox draft update <draftId> --base-version <version> --text "..." --json

That prompt is deliberately small. The agent does not need to understand all of Tinbox to be useful; it needs the check, read, draft, and probe habits.

For a more ambitious agent, add a one-paragraph brief:

You help book shows for an independent artist. Use bookings@studio.com. Find
venue contacts, send or draft short booking pitches when asked, track every
reply, summarize availability, and prepare follow-ups. If a venue asks for a
commitment, price, contract term, or date confirmation, draft the reply and ask
the operator before sending.

Or:

You help submit a nonfiction book proposal. Use rights@author.com. Contact
literary agents, newsletters, festivals, podcasts, and rights departments when
asked. Keep a table of who was contacted, what they requested, and the next
follow-up date. Draft every outbound email for review unless the operator says
you may send this specific message.

Monitor new mail

For a long-running agent, keep a watermark and ask what changed since that watermark:

tinbox threads --changed-since 2026-07-08T00:00:00Z --inbox support-bot --json

The response includes a server now. Store that as the next watermark:

{
  "since": "2026-07-08T00:00:00Z",
  "now": 1783531200000,
  "threads": [
    {
      "id": "thr_...",
      "inboxId": "ibx_...",
      "lastMessageAt": 1783531180000,
      "updatedAt": 1783531180000,
      "state": "open",
      "status": "active"
    }
  ]
}

If threads.length reaches the command limit, poll again soon. For most agent mailboxes, a 30-60 second loop is enough:

1. Run threads --changed-since with the last server watermark.
2. For each changed thread, read tinbox thread <id>.
3. Draft if action is obvious.
4. Ask the operator when uncertain.
5. Store the returned now as the next watermark.

The rule is: breadth can come from the git archive, but the present comes from the API. Before the agent acts, it probes live state.

Safe reply workflow

The safe reply workflow is:

tinbox threads --unanswered --inbox support-bot --json
tinbox thread thr_... --json
tinbox draft create --thread thr_... --text "Thanks, I am looking into this." --json
tinbox draft version drf_... --json
tinbox draft update drf_... --base-version 1 --text "Thanks — I found the issue and..." --json

A stale --base-version fails with a conflict instead of overwriting another human or agent. Re-read the draft, rebuild the edit on the current version, and retry.

Only grant send authority when the agent is allowed to send from that address without another human click. Even then, sending is ledgered and idempotent:

tinbox draft send drf_... --json

For review-first teams, leave the draft in Tinbox for a human to approve, or export it into the outbox PR lane:

tinbox draft export drf_... --json

Merging an outbox reply makes the draft ready. It does not send by itself.

Connect over MCP instead

If the agent runtime supports MCP, connect it to the deployment's /mcp endpoint instead of giving it only shell commands. The same tools are exposed there, with the same inbox token and the same authorize() checks.

Use MCP when the agent should call tools natively. Use the CLI when the agent is working in a terminal or CI-style loop. Both surfaces are backed by the same tool manifest.

See Connect an MCP client for the setup steps.

For a first agent mailbox:

SettingStart with
Inbox typeshared
Token roleviewer for read-only, agent for drafting
Send permissionoff until you trust the workflow
Monitor loopthreads --changed-since every 30-60 seconds
Work selectionthreads --unanswered plus full thread reads
Human reviewrequired for sends, campaigns, imports, and routing changes

This is the product boundary Tinbox is built around: the agent gets a real email address and useful hands, but irreversible actions stay human-gated unless a human deliberately grants that authority.

Next steps