BotintoMailbox tutorials

Set up Botinto
with Cloudflare.

Cloudflare routes incoming mail to an Email Worker. The Worker sends it to Botinto PHP, which stores messages in your database and private originals and attachments in R2.

1. Prepare PHP hosting and the database

Deploy the supplied website to PHP hosting with HTTPS at botinto.com. Import the included db/botinto_db.sql into an empty database, or apply the supplied rebrand migration to an existing original import. The full export already contains the email tables. Keep SQL files outside the web root. Set the actual database credentials in admin/config.php; preserve APP_KEY for imported encrypted data.

The private deployment bundle includes docs/BOTINTO-SETUP.html with Google, DNS, administrator, SMTP, migration and acceptance-test instructions. Configure system SMTP and verify the account matching ADMIN_EMAIL before using platform admin.

2. Create private R2 storage

  1. Create the botinto-email bucket in the new Cloudflare account. Keep public access and r2.dev disabled.
  2. Create bucket-scoped Object Read & Write S3 credentials. Save the Access Key ID, Secret Access Key and S3 endpoint.
  3. Set all four EMAIL_R2_ENDPOINT, EMAIL_R2_KEY, EMAIL_R2_SECRET and EMAIL_R2_BUCKET constants in config.php, or leave them all undefined and configure the new account in platform admin → Email files · private Cloudflare R2.
  4. Copy historical objects from the old bucket with their exact keys before switching storage. Changing account credentials does not move files. Test old attachments and original emails afterward.

PHP uploads to R2 directly. The Email Worker needs no R2 binding.

3. Deploy the Email Worker

  1. Create a Worker named botinto-email. Paste the complete cloudflare/botinto-email-worker.mjs from the deployment bundle and deploy.
  2. Generate a private random receiving key in Botinto admin, or define WEBHOOK_SECRET and EMAIL_RECEIVING_DOMAIN in config.php. Use botinto.com as the receiving domain.
  3. Add the identical raw key as the Worker's production secret WEBHOOK_SECRET. Set BOTINTO_EMAIL_ENDPOINT to https://botinto.com/incoming.php.
  4. Leave Cron Triggers, Queues and R2 bindings empty for this Worker. No HTTP route or custom Worker domain is required.

File-based configuration overrides imported database settings. Keep secret values out of URLs. The Worker retries transient failures within the current event; it has no durable retry queue and rejects delivery if PHP does not confirm success.

4. Enable domain email routing

In the new account, onboard botinto.com for Email Routing using Cloudflare's generated DNS records. First verify an external destination mailbox and create an explicit rule for [email protected] to that mailbox. Then enable Catch-all → Send to a Worker → botinto-email. Keep explicit routes for other business addresses.

Cloudflare must handle the incoming MX for this root-domain receiving setup. Do not mix its MX with Google Workspace or cPanel MX for the same domain. A separate receiving subdomain requires deliberate application and Worker changes. Ordinary addresses routed only to the Worker can be rejected unless Botinto recognizes them.

5. Connect mailboxes and sending

Open Email tickets → Manage mailboxes and copy the actual private receiving ID. Update provider forwarding to that address, retain the original mailbox copy and complete confirmation again where needed. Configure SMTP separately for each mailbox and verify sending. Google login does not grant Gmail access. Follow the mailbox guide.

6. Configure background jobs separately

Use hosting cron for app/worker.php --cron --interval=60, or deploy the separate optional cloudflare/botinto-scheduler-worker.mjs with BOTINTO_CRON_KEY from platform admin and a matching Cron Trigger. Choose one scheduler. Account emails and AI jobs need it; incoming forwarded mail does not. See hosting and cron setup.

7. Confirm actual delivery

Send a new email from another account with a small attachment. Confirm the original provider copy, correct Botinto workspace ticket, attachment download and SMTP reply. Also test a historical R2 attachment. The web preview is not an email event and returns 405 intentionally.

Hosting must accept at least a 12 MiB request for the 8 MiB raw MIME limit. A 401 suggests the shared secret; a 404 suggests the recipient or mailbox connection; a 413 suggests body limits. Challenges or HTML responses indicate WAF/Access or routing issues. Scope any machine-request exception narrowly and keep application authentication enabled.

Local checks cannot verify live account credentials, DNS, SMTP or Cloudflare delivery.