Skip to content
Inbot
Esc
↑↓navigate↵open⌘Jpreview
On this page

Mail transport

Create the Cloudflare API token Inbot needs, with every permission explained, then verify, save, rotate and clear it safely.

The mail transport is the Cloudflare account Inbot uses to receive and send mail. Inbot talks to Cloudflare’s API with one API token that you create and store in Inbot’s encrypted database. Sending, domain provisioning, inbound pulling and remote access all need it.

Required token permissions

Scope Permission Level Used for
Zone Zone Read Find the zone that holds your mail domain
Zone DNS Edit Snapshot and manage mail DNS records, and the remote access hostname
Zone Zone Settings Edit Enable and unlock Email Routing DNS for the mail subdomain
Zone Email Routing Rules Edit Route each inbox, and the verification self-test address, to the Worker
Account Email Sending Edit Sending subdomains, their DNS, outbound mail and the self-test
Account Workers Scripts Edit Upload and manage the inbound Email Worker
Account Workers R2 Storage Edit The encrypted inbound bucket, and reading and deleting its objects
Account Queues Edit Inbound and delivery-event Queues, their consumers and event subscriptions
Account Cloudflare Tunnel Edit Optional, only for remote access

The same list drives the web app’s Required permissions table, the prefilled token link and the errors Inbot shows when a permission is missing, so they cannot disagree.

Configure it in the web app

Open Settings > Mail transport.

  1. Select Create API token. Cloudflare’s token page opens with Inbot’s permissions prefilled and the name Inbot.
  2. The template starts with all accounts and all zones. Narrow Account Resources to your account and Zone Resources to your mail zone before you create the token.
  3. Paste the token into API token. Leave Account ID empty unless the token reaches several accounts.
  4. Select Verify and save.

The token field is a password field that clears when you submit. Inbot never returns, displays or logs the token again.

What verification checks

Verification confirms that the token is active and finds its account:

  • Without an account ID, Inbot verifies the token and lists the accounts it can reach. With exactly one account, that account is selected. With none or several, you get action_required listing each account’s name and ID; submit again with the right ID.
  • With an account ID, Inbot verifies the token against that account.

Verification does not prove the token has every permission or that its resource scopes include your zone. Cloudflare checks each call when it happens, and a refused call becomes a missing_permission error that names the missing permission and asks you to save a replacement token. If verification fails, the previous configuration stays in place.

Configure it with the CLI

The transport is owner-only and there is no MCP tool for it. On the machine that runs Inbot, the CLI acts as the owner. The token is never accepted as a command argument. Provide it on stdin or in the environment:

inbot transport status
# Read the token from a password manager or a file descriptor:
inbot transport configure --token-stdin
# Or from the environment:
INBOT_CLOUDFLARE_API_TOKEN=... inbot transport configure --account-id ACCOUNT_ID
inbot transport clear

--account-id is optional, as in the web app. configure verifies the token and then saves it; there is no separate verify command. If the token reaches several accounts it returns action_required (exit 6) listing them. A failed verification keeps the previous configuration. status never returns the token. clear follows the rules in Clear it.

Configure it with the API

TOKEN=$(jq -r .token ~/.inbot/connection.json)
curl -s http://127.0.0.1:8025/v0/owner/transport \
  -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"api_token":"<cloudflare token>"}'
Route Result
GET /v0/owner/transport provider, account_id, token_set, verification_status (not_configured, unverified, verified) and verified_at
PUT /v0/owner/transport { "api_token", "account_id"? }. Verifies, then saves. account_id is 32 hex characters.
DELETE /v0/owner/transport Clears the configuration. Repeating it is safe.

Rotate or change accounts

  • Rotate by saving a new token for the same account. Changes take effect on the next loop cycle, without a restart.
  • Change accounts only after tearing down and deleting every domain registration and disabling remote access. Inbot refuses a token for a different account while either still belongs to the old one.

Clear it

DELETE /v0/owner/transport, or Clear transport in Settings, returns action_required while remote access is enabled or any domain still has provisioned resources. Tear down domains and disable remote access first. Clearing keeps your local mail, the inbound decryption key and your domain registrations.