For builders

Wire your inbox to your apps

BumbleBox classifies inbound email and emits HMAC-signed events your systems consume — invoices, tenders, contracts, deadlines, with the fields already extracted. Connect any app in about five minutes.

Receive

Drop one zero-dependency file into your app. It verifies the HMAC signature for you.

Act

Your handler gets clean, extracted fields — write them straight to your system.

1. Receive events

One zero-dependency file (Node crypto only). It verifies the signature; your handler gets clean data. Not Express? Use the framework- agnostic verify() core (Cloudflare Workers, Lambda, n8n).

const express = require('express');
const { expressReceiver } = require('./lib/bumblebox-receiver');

app.post(
  '/api/integrations/bumblebox',
  express.raw({ type: '*/*', limit: '1mb' }),   // RAW body — required for HMAC
  expressReceiver(process.env.BUMBLEBOX_WEBHOOK_SECRET, {
    'email.tender_detected': async (data) => {
      // data.extracted = { reference, deadline, buyer }
      await db.tenders.insert(data.extracted);
    },
    'email.invoice_detected': async (data) => {
      // data.extracted = { amount, currency, reference, dueDate }
    },
  })
);

2. Register a subscription

Tell BumbleBox where to send events and which ones. The signing secret is returned once — store it in your app's BUMBLEBOX_WEBHOOK_SECRET. Optional filters by category, sender or keyword.

curl -X POST https://api.bumblebox.ai/api/inbound-subscriptions \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Origin: https://bumblebox.ai" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My app",
    "endpointUrl": "https://myapp.com/api/integrations/bumblebox",
    "events": ["email.tender_detected"],
    "filterKeywords": ["appel d offres", "marché public"]
  }'
# → { "id": "...", "signingSecret": "whsec_..." }  ← put whsec_ in your env

Event catalog

Every payload carries from, subject, classification, confidence, messageId, extracted. The extracted object depends on the event:

email.classified— (the firehose: every classified email)

email.invoice_detectedamount, currency, reference, dueDate

email.tender_detectedreference, deadline, buyer

email.contract_detectedparty, signBy

email.deadline_detecteddeadline

How the signature works

X-BumbleBox-Signature: t=<unix_ts>,v1=<hex>
v1 = HMAC_SHA256(secret, `${t}.${rawBody}`)

The kit verifies over the raw body, rejects timestamps older than 5 minutes (anti-replay) and compares with a constant-time check. Re-scans re-send the same event for the same email — dedup on messageId.

Already in production

A public-tender email lands in a mailbox, becomes an email.tender_detected event, and is created as a watch-list entry in Marchéspublics — automatically, signature-verified, no human triage.