Bounty Mail (bmail); A tiny inbound email inbox for autonomous agents, built on the Cloudflare Free plan; Giving an agent direct access to our mailboxes is very concerning. With bmail, an email could be routed to Cloudflare Workers and tells the Agent to poll for messages. Useful if testing for Registration Features that requires Email Access; Peoples are always lazy such as handling over the OTP to the Agents.
- Cloudflare Workers receive mail and serve the REST API.
- Cloudflare Email Routing handles MX, catch-all, and literal address rules.
- Cloudflare R2 stores the raw message and a per-address latest marker.
- ARTEX polls the REST API through the custom tools in
artex-custom-tools.json. bmail ships no client and no UI.
bmail is the inbound mailbox for ARTEX, the self-hosted autonomous penetration testing platform. ARTEX creates the custom tools from artex-custom-tools.json; bmail stores the mail those tools read.
No database, no aliases, no bundled integrations. One Worker, one R2 bucket, one shared key.
- Cloudflare products used
- Architecture
- Flow
- Recipient allowlist
- Requirements
- Setup
- Deploy with the Cloudflare dashboard
- Configuration
- Local development
- Sanity check
- REST API
- ARTEX custom tools
- Ack and lifecycle
- Free plan budget
- Observability
- Troubleshooting
- Project layout
- Security notes
- Limits
- License
| Product | Role in bmail | Free plan note |
|---|---|---|
| Cloudflare Workers | Runs the email() ingest handler and the HTTPS REST API. |
100,000 requests/day, 10 ms CPU per invocation. |
| Cloudflare Email Routing | Receives mail at the domain MX, applies catch-all or literal rules, invokes the Worker, and prepends a trusted Authentication-Results header. |
Free. 25 MiB inbound limit, 200 routing rules per domain. Routing rules decide what reaches the Worker; bmail applies a second allowlist. |
| Cloudflare R2 | Stores mail/<address>/<id>.eml and the latest/<address> marker. Serves list, head, get, and delete operations. Holds the lifecycle rule. |
10 GB-month, 1M Class A and 10M Class B operations/month, free egress. |
| Cloudflare DNS | Hosts the zone, MX records, and the domain used by Email Routing. | Included with the zone. |
| Wrangler | Local dev, deploy, secret upload, and r2 bucket lifecycle set. |
CLI. |
| Workers Logs | Persisted invocation and custom logs, visible in the dashboard. | Free: 200,000 log events/day, 3-day retention. |
Not used, on purpose: D1, KV, Durable Objects, Queues, Pages, Access, and Email Sending. The only state lives in R2.
Internet mail
|
v
Cloudflare Email Routing (MX, catch-all)
| |
| +--> optional forward --> personal inbox (archive)
v
Cloudflare Worker email()
|
v
Cloudflare R2
mail/<address>/<id>.eml + latest/<address>
ARTEX -- HTTPS + Bearer --> Cloudflare Worker fetch()
|
+--> R2 head / list / get / delete
- Pick an address that matches the allowlist, for example
test@mail.example.comorbbounty@programs.example.net. - Cloudflare Email Routing delivers it to the Worker.
- The Worker stores the raw MIME in R2 and updates
latest/<address>. - ARTEX polls the REST API, or you inject a local email during development.
- It reads the raw message and parses it in your own code.
- After a successful read,
DELETE /v1/inbox/:address/:idremoves the R2 copy. Your forwarded archive is unaffected. - The R2 lifecycle rule deletes anything that was not acknowledged after
bmail_lifecycle_days.
There is no registration step. The Worker accepts addresses that match its recipient allowlist.
bmail_mail_domains accepts two forms:
mail.example.com- any local part on that domain.bbounty@programs.example.net- exactly that address.
There is no wildcard syntax. Use the bare domain when you want every local part. *@mail.example.com and * are rejected with a wildcards are not supported error.
For example:
bmail_mail_domains=mail.example.com,bbounty@programs.example.netThis accepts test@mail.example.com and bbounty@programs.example.net, but drops other@programs.example.net.
Email Routing is the first gate. It decides which mail reaches the Worker:
- A catch-all rule sends every local part to the Worker. Pair it with a domain entry.
- A literal rule sends one address to the Worker. Pair it with an exact address entry.
A common setup is one catch-all domain plus one fixed program address:
mail.example.com catch-all -> bmail Worker
bbounty@programs.example.net literal -> bmail Worker
programs.example.net catch-all -> personal inbox (archive)
The literal rule wins over the catch-all, so only bbounty@programs.example.net reaches the Worker on that domain.
- Cloudflare account on the Free plan.
- A domain on Cloudflare with Email Routing.
- An R2 bucket.
- Node.js 22 or newer, pnpm 10 or newer.
pnpm install
cp .env.example .env
# fill in bmail_mail_domains, bmail_api_key, cloudflare_r2_bucket_name
wrangler login
wrangler r2 bucket create <cloudflare_r2_bucket_name>
pnpm deploy:workerpnpm deploy:worker deploys the Worker, uploads bmail_api_key as a secret, and sets the R2 lifecycle rules.
The Deploy to Cloudflare button next to the Workers badge targets the public its0din-ai/bmail repository. It provisions the R2 binding from wrangler.jsonc. Set bmail_mail_domains and bmail_api_key in Settings > Variables and Secrets after it finishes.
The repository must be public and pushed for the button to work. After it finishes, configure Email Routing and add the R2 lifecycle rules manually, because the one-click flow does not run pnpm deploy:worker.
If the button fails or you use a fork, point the url parameter at your public repository root.
Then in the Cloudflare dashboard:
- Enable Email Routing on each domain used in
bmail_mail_domains. - For a catch-all domain, set the catch-all action to the
bmailWorker. - For a single address, create one literal routing rule to the
bmailWorker. - If you want a personal archive, do not give the same rule two actions. Either use a literal rule for the agent address and leave the catch-all forwarding to your inbox, or run bmail on a separate subdomain with its own catch-all.
Use this path if you want to create and configure the Worker in the Cloudflare web UI. The in-browser editor path uses the bundled dist/index.js, which you build locally with pnpm build. The Git-based flow builds from source in Cloudflare.
The in-browser editor does not read wrangler.jsonc and does not run scripts/deploy.mjs, so bindings, variables, and the R2 lifecycle rules are set by hand. The Git flow uses wrangler.jsonc for the Worker name, entry point, and R2 binding; variables and lifecycle rules are still manual.
| Path | Config source | Lifecycle rule |
|---|---|---|
CLI (pnpm deploy:worker) |
.env and wrangler.jsonc |
Applied by the script. |
| Dashboard editor | UI bindings and variables | Added manually in R2 settings. |
| Dashboard Git | wrangler.jsonc plus UI variables |
Added manually in R2 settings. |
- Cloudflare dashboard > R2 object storage > Create bucket.
- Name it, for example
bmail-mail, and create it.
- Workers & Pages > Create application.
- Choose the in-browser Worker or Hello World option if your account shows it.
- Name it
bmailand deploy. - Open the Worker and select Edit code (some accounts label this Quick Edit).
If your account only shows the Git-based Create application flow, use that instead:
- Push this repository to GitHub or GitLab.
- Connect it in Workers & Pages > Create application.
- Root directory: the repository root.
- Build command:
pnpm install. - Deploy command:
npx wrangler deploy. - Create the R2 bucket with the name in
wrangler.jsonc(bmail-mail), or edit that file before pushing. - Add
bmail_mail_domainsandbmail_api_keyin the dashboard as described in step 4 below.
Skip this step if you used the Git-based flow; it deploys from source.
The dashboard editor is safest with JavaScript, so use the bundled Worker instead of the TypeScript source.
pnpm install
pnpm build- Open
dist/index.js. - Replace the editor contents with that file.
- Remove the final
//# sourceMappingURL=index.js.mapline if it is present. - Select Deploy.
If your editor accepts TypeScript, src/index.ts also works.
In the Worker settings:
- Bindings > Add binding > R2 bucket:
- Variable name:
MAIL - Bucket: the bucket you created
- Skip this if you used the Git flow;
wrangler.jsoncalready declares the binding.
- Variable name:
- Variables and Secrets:
bmail_mail_domainsas text: a comma-separated allowlist. A domain accepts any local part; a full address is exact. For examplemail.example.com,bbounty@programs.example.netbmail_api_keyas a secret: at least 16 random characters
Do not add cloudflare_r2_bucket_name as a Worker variable. It is only read by pnpm deploy:worker; the dashboard path uses the R2 binding instead.
Save and deploy. The API returns 503 until the binding and key exist.
Go to Settings > Runtime > Compatibility date and use 2026-03-12 or a later date supported by your account. No compatibility flags are required.
Go to R2 object storage > your bucket > Settings > Object lifecycle rules:
- Rule
bmail-expire-mail, prefixmail/, delete after 7 days. - Rule
bmail-expire-latest, prefixlatest/, delete after 7 days.
Use a longer window if you want more recovery time. New rules can take up to 24 hours to apply. The Worker does not need bmail_lifecycle_days in the dashboard path; that variable is only used by pnpm deploy:worker.
Go to Compute > Email Service > Email Routing, or the zone's Email > Email Routing page:
- Enable Email Routing for the domain. For a subdomain, add it under Settings > Subdomains first.
- For a catch-all domain: Routing rules > Catch-all > action Send to Worker >
bmail. - For one address: Create routing rule, enter the local part, action Send to Worker >
bmail. - If you need a personal archive, remember that a catch-all has only one action. Use a literal rule for the agent address to the Worker and leave the catch-all forwarding to your inbox, or run bmail on a separate subdomain.
curl https://<worker-url>/healthThen send a message to test@mail.example.com and list it:
curl 'https://<worker-url>/v1/inbox/test%40mail.example.com' \
-H "authorization: Bearer <bmail_api_key>"The following values are only used by the CLI deploy script, so you can leave them out of the dashboard path: bmail_lifecycle_days, cloudflare_worker_name, cloudflare_r2_bucket_name, cloudflare_account_id.
bmail_mail_domainsis a plaintext runtime variable. Set it in Settings > Variables and Secrets.wrangler.jsoncsetskeep_vars: true, so a deploy does not delete it.bmail_api_keymust be a runtime secret, not a build secret. Deploys do not delete secrets.- Build variables and secrets are available only during the build. The Worker cannot read them with
env.*. - Do not add
bmail_api_keytovarsor commit it.
.env is the source of truth. pnpm dev writes .dev.vars; pnpm deploy:worker maps the values to Worker vars and secrets.
| Key | Used by | Purpose |
|---|---|---|
bmail_mail_domains |
Worker | Comma-separated allowlist. Domain entries accept any local part; full-address entries are exact. |
bmail_api_key |
Worker and smoke test | Shared bearer key, 16+ characters. |
bmail_lifecycle_days |
CLI deploy | R2 expiry for mail/ and latest/, default 7. The dashboard path sets these rules in the UI. |
cloudflare_worker_name |
Deploy | Worker name. |
cloudflare_r2_bucket_name |
Deploy | R2 bucket name. |
cloudflare_account_id |
Deploy | Optional account id. |
bmail_api_url |
Smoke test | Worker base URL. |
bmail_address |
Smoke test | Optional default address. |
bmail_local_email_url |
Smoke test | Optional local email injection base. Defaults to bmail_api_url when it is localhost. |
pnpm devpnpm dev writes .dev.vars from .env and listens on 127.0.0.1:8787.
Send a local message:
curl --request POST 'http://127.0.0.1:8787/cdn-cgi/handler/email?from=sender@example.com&to=test@mail.example.com' \
--data-raw 'From: sender@example.com
To: test@mail.example.com
Subject: Test
Content-Type: text/plain
Your code is 123456.'Read it:
curl 'http://127.0.0.1:8787/v1/inbox/test%40mail.example.com' \
-H "authorization: Bearer $bmail_api_key"# terminal 1
pnpm dev
# terminal 2
bmail_api_url=http://127.0.0.1:8787 \
bmail_api_key=<your key> \
bmail_address=test@mail.example.com \
pnpm smokeOn a local API the script injects a test email through /cdn-cgi/handler/email, then checks:
/health- wrong key returns 401
- unlisted address returns 403
- message appears in the list
- raw MIME contains the marker
- ack returns 204
- raw after ack returns 404
- the message disappears from the list
bmail_api_url=https://<worker-url> \
bmail_api_key=<your key> \
bmail_address=test@mail.example.com \
pnpm smokeThe script prints a unique subject and waits up to 90 seconds. Send a real email from any mailbox to that address with that exact subject. It then runs the same list, raw, and ack checks.
A deployed Worker cannot inject mail into Email Routing, so the real email is required.
GET /healthreturns{ "ok": true, "ready": true }and all three checks pass.- Send a message with a unique subject.
GET /v1/inbox/<address>returns metadata; copy theid.GET /v1/inbox/<address>/<id>returns the raw MIME with your marker.DELETE /v1/inbox/<address>/<id>returns204.- The raw route now returns
404, and the list no longer contains that id. - R2 > your bucket > Objects: the object count drops after ack.
- Compute > Email Service > Email Routing > Activity log: the message shows
Handledplus SPF, DKIM, and DMARC results. - Wrong key returns
401. An address outside the allowlist returns403. - If you use an exact address entry, send to a different local part on that domain. It should be dropped and never appear in the list.
Example curl checks:
curl https://<worker-url>/health
curl 'https://<worker-url>/v1/inbox/test%40mail.example.com' \
-H "authorization: Bearer $bmail_api_key"
curl 'https://<worker-url>/v1/inbox/test%40mail.example.com/<id>' \
-H "authorization: Bearer $bmail_api_key"
curl -X DELETE 'https://<worker-url>/v1/inbox/test%40mail.example.com/<id>' \
-H "authorization: Bearer $bmail_api_key"All /v1 routes require Authorization: Bearer <bmail_api_key>.
| Route | Purpose |
|---|---|
GET /health |
Liveness and readiness checks. |
GET /v1/inbox/:address?after=<cursor>&limit=<n> |
List message metadata, paged with next_cursor. |
GET /v1/inbox/:address/:id |
Raw RFC 5322 message. |
DELETE /v1/inbox/:address/:id |
Acknowledge and delete the stored copy. |
The address must be URL encoded. after is the next_cursor from the previous response. limit is 1 to 200, default 50. Delete is idempotent and returns 204.
Parsing is your tool's job. The Worker stores and returns bytes; it does not parse MIME.
The repository includes artex-custom-tools.json, three HTTP custom tool definitions for ARTEX:
bmail_list_messagesbmail_get_messagebmail_ack_message
To install them:
-
Open
artex-custom-tools.jsonand replaceYOUR_WORKER_URLwith the fullhttps://Worker URL, andYOUR_BMAIL_API_KEYwith the shared key. -
Feed the whole file into the ARTEX chat.
-
Ask the ARTEX auto agent:
Create these custom tools with
create_custom_tool, bind them to my agent, and enable them.
The auto agent has the create_custom_tool platform tool by default. If you use another agent, change agents in every tool entry before feeding the file.
After creation, verify with a prompt such as:
Use bmail_list_messages for test@mail.example.com.
Notes:
- ARTEX HTTP tools make a single request. For waiting, call
bmail_list_messagesagain with the previousnext_cursorasafter. bmail_get_messagereturns raw MIME. Parse it in ARTEX or with another tool.bmail_ack_messagedeletes the R2 copy. It is destructive; call it only after a successful read.- The API key is stored in the tool's Authorization header. ARTEX masks header values in its tool UI. If you do not want the key in the chat transcript, create the tools with a placeholder and set the header in the ARTEX UI afterward.
DELETE /v1/inbox/:address/:idremovesmail/<address>/<id>.emlimmediately.- The
latest/<address>marker may still point at the deleted object. New mail updates it, so this is harmless. pnpm deploy:workersets two R2 lifecycle rules,mail/andlatest/, each expiring afterbmail_lifecycle_days(default 7).- The lifecycle command replaces the bucket's lifecycle configuration, so use a dedicated bucket or merge your own rules into the generated file.
| Operation | R2 class | When |
|---|---|---|
| Store a message | Class A | 2 per received email: the .eml plus the latest marker. |
| Read a message | Class B | 1 per raw read. |
| Poll with a cursor and no new mail | Class B | 1 head per poll. |
| Poll that finds new mail | Class B + A | 1 head plus 1 list. |
| List without a cursor | Class A | First call only. |
| Acknowledge a message | Free | 1 DeleteObject per ack. |
A cursor poll does not call ListObjects unless the latest marker says something newer exists. That keeps polling cheap.
R2 Free includes 1M Class A operations, 10M Class B operations, and 10 GB-month of storage. Workers Free includes 100,000 requests/day. Your polling interval determines the request count; the Worker does not impose one.
wrangler.jsonc enables Workers Logs at 100% sampling:
- View persisted logs in Workers & Pages >
bmail> Observability. - Workers Free includes 200,000 log events per day with 3-day retention.
- The Worker emits custom logs for
bmail: received,bmail: stored, config problems, and R2 write failures. It does not log message bodies or the API key. wrangler tail bmailstill works for real-time logs and does not depend on the persistence setting.- The in-browser editor path does not read
wrangler.jsonc. If you use that path, enable Observability in the Worker settings.
GET /health reports the three runtime prerequisites:
{
"ok": true,
"ready": false,
"version": "0.1.0",
"checks": {
"bmail_mail_domains": { "present": true, "valid": true },
"bmail_api_key": { "present": false, "valid": false },
"r2_binding": false
}
}present: false- the variable or secret is not on the running Worker version. Check the environment (Production vs Preview), make sure it is a runtime variable and not a build variable, and deploy a new version.present: trueandvalid: false- the value exists but is unusable. Forbmail_mail_domains, check quotes, wildcards, or an empty entry. Forbmail_api_key, the value must be at least 16 characters.r2_binding: false- add an R2 bucket binding with variable nameMAIL. A plain text variable namedMAILdoes not count; the check requires the R2 API. An environment variable namedcloudflare_r2_bucket_nameis not a binding and the Worker does not read it.
Make the change, deploy a new version, and call /health again. The Worker also logs a bmail: not ready {...} line with the same presence and validity flags, visible in wrangler tail.
The Email Routing activity log only reports a generic upstream error. The Worker log has the actual exception.
- Start live logs:
Or open the Worker in the dashboard and use Logs > Real-time logs.
wrangler tail bmail
- Send another test email.
- Look for:
bmail: received <address> size=<n>- the handler started.bmail: stored <address> id=<id>- the R2 writes succeeded.bmail: MAIL is not an R2 binding- delete any plain variable namedMAILand add an R2 bucket binding namedMAIL.bmail: R2 message write failed- the binding exists but the write failed; check the bucket still exists, the binding points to the right bucket, and R2 usage is within quota.Provided readable stream must have a known length- the deployed Worker is older than theFixedLengthStreamfix. Production R2 rejects unknown-length streams, while local R2 is more permissive. Redeploy the currentsrc/index.ts.
If there is no bmail: received line, the running Worker does not have the email handler or your recipient allowlist rejected the message before storage.
Also re-check /health. r2_binding should still be true after the deployment that added your variables. A redeploy from wrangler.jsonc can replace a dashboard binding if the bucket name in the file is different.
{
"error": {
"code": "config_invalid",
"message": "bmail_mail_domains is missing or invalid"
}
}The Worker parses bmail_mail_domains before it checks the API key, so this error is not about the key.
Check:
- The variable exists on the Worker that serves this URL, in the environment you are calling (production vs preview).
- The name is exactly
bmail_mail_domains. - The value is a comma-separated list with no surrounding quotes, for example
mail.example.com,bbounty@programs.example.net. Do not use*@mail.example.comor*; use the bare domain instead. - Dashboard and Git deploys do not read
.env. Add the variable under Settings > Variables and Secrets. - Deploy a new version after changing it.
- Run
wrangler tail <worker-name>and call the endpoint again. The Worker log shows the exact parse error, for example an empty value or an invalid domain.
A CLI deploy also passes bmail_mail_domains from .env with --var, so make sure .env has the value you want for that deployment.
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid API key"
}
}Check Authorization: Bearer <bmail_api_key>. The key must match the Worker secret exactly and be at least 16 characters.
src/ Worker source: email() ingest and REST API
test/ Worker tests
scripts/ dev, deploy, and smoke helpers
assets/ README banner
artex-custom-tools.json ARTEX HTTP custom tool definitions
wrangler.jsonc Worker configuration
- One shared key grants access to every configured address. Rotate it by changing
bmail_api_key. - Keys are compared in constant time and the key is never logged.
- Addresses are validated before being used in an R2 key, so a local part cannot escape its prefix.
- Only the first
Authentication-Resultsheader withmx.cloudflare.netas authserv-id is trusted for DMARC. - R2 is private. Only the Worker binding reads it.
- MIME parsing happens in your tool, not in the Worker.
- The forwarded personal archive is the source of truth. Ack only removes the R2 copy.
- There is no rate limiting. The Workers daily request cap is the backstop.
- Inbound message size is capped by Cloudflare at 25 MiB.
limitis capped at 200 per list call.- There is no bundled client or UI.
- There is no alias manager, outbound mail, or D1.
Not set yet.