What do you need?
- A toolchain that builds WebAssembly components for wasm32-wasip2 (Rust is the common choice)
- A nofeb key with hook:manage
Steps
-
1. Get the interface
The world is versioned,
nofeb:hooks@0.1.0; additions arrive as new minor versions and components built against older ones keep working. It is served publicly, so a build can fetch it.The world, abridged curl https://api.nofeb.com/v1/hooks/wit interface handler { inbound-resolve: func(request: string) -> result<string, string>; inbound-pre-deliver: func(request: string) -> result<string, string>; outbound-pre-send: func(request: string) -> result<string, string>; } world hook { import host; export handler; } -
2. Write the stage you need
A component implements the stages it is registered for and answers an error for the others. At inbound.pre_deliver the request's
dataholds the inbox, sender, recipients, subject, a preview, the reply text, any codes, whether the mail is automated, whether it has attachments and the receiving server's security verdict. The answer accepts, rejects or quarantines, and can add keywords and metadata.Request and answer at inbound.pre_deliver request: {"id": "hki_…", "stage": "inbound.pre_deliver", "org_id": "org_…", "created_at": "…", "data": {"inbox_id": "inb_…", "from": […], "subject": "Invoice INV-7", "preview": "Amount due: EUR 120.00", …}} answer: {"action": "accept", "keywords": ["invoice"], "metadata": {"category": "invoice", "invoice_number": "INV-7"}} -
3. Register the hook
A wasm hook has no URL. Choose its scope (organization, pod or inbox), its timeout, and what a failure means: fail_open lets mail through, fail_closed stops it. Sandbox settings are optional:
fuel(100 million by default),memory_mb(32 by default) andallow_urls.Create it curl -X POST https://api.nofeb.com/v1/hooks -H "Authorization: Bearer $NOFEB_ADMIN_KEY" -H 'content-type: application/json' \ -d '{"stage": "inbound.pre_deliver", "target": "wasm", "scope": "org", "timeout_ms": 1000, "failure_mode": "fail_open", "memory_mb": 16}' -
4. Upload and test
Each upload becomes a new active version after nofeb has compiled, linked and instantiated it; a module that fails any of those is refused and the previous version stays. The test call runs the hook on sample data, or on data you give, and returns its decision and log.
Upload, then try it curl -X POST https://api.nofeb.com/v1/hooks/hok_…/module -H "Authorization: Bearer $NOFEB_ADMIN_KEY" \ -H 'content-type: application/wasm' --data-binary @label_invoices.wasm curl -X POST https://api.nofeb.com/v1/hooks/hok_…/test -H "Authorization: Bearer $NOFEB_ADMIN_KEY" -H 'content-type: application/json' \ -d '{"data": {"subject": "Invoice INV-7 attached", "preview": "Amount due: EUR 120.00", "from": [{"email": "billing@acme.example"}]}}' -
5. Roll back if you need to
The newest ten versions are kept. PATCH /v1/hooks/{hook_id}/module with
versionmakes an older one active again, and the same call changes fuel, memory and the URL allowlist.
What can the module reach?
Nothing by default: no filesystem, environment, arguments, sockets or standard streams. Clocks and random numbers are available. Everything else is a host function: write to the invocation log, read and set metadata on what the stage is deciding about, read the metadata of an inbox or thread the hook covers, and fetch URLs that start with an allow_urls prefix. Fetches follow no redirects, never reach private addresses, carry at most 1 MiB each way and number at most eight per call.
A trap, an error answer, running out of fuel or memory, or a timeout counts as a failed call, and the hook's failure mode decides, exactly as for an HTTPS hook that errors. The invocation log records the status, fuel used, module version and the module's own log lines.
When is an HTTPS hook the better choice?
When the decision needs your database or a service you cannot expose as an allowlisted URL. HTTPS hooks take the same request and answer the same JSON, so a module and an endpoint are interchangeable, and both can run at the same stage with their effects merged.
Frequently asked questions
Can I run WebAssembly on inbound email?
Yes. Register a wasm hook at inbound.pre_deliver and nofeb runs your component on every message in its scope before delivery, sandboxed, with its decision applied like an HTTPS hook's.
Which languages can I write a hook in?
Any language whose toolchain builds a WebAssembly component for the published WIT world. The functions exchange JSON strings, so a hook needs no nofeb library to parse its input.
What does a hook cost in latency?
The hook's timeout_ms bounds it (between 100 ms and 10 s, 5 s by default), including time spent fetching URLs. Compiled modules are cached, so a call does not recompile.
Status of everything on this page
Every capability named above, with its status as reconciled against the engine.
| Capability | What it does | Status |
|---|---|---|
| WebAssembly hooks | The same pipeline stages as HTTPS hooks, run as a WebAssembly module you upload, built against a published, versioned interface. Modules run sandboxed with fuel, memory and time limits, can fetch only the URLs you allow, read and set metadata on what they decide about, and keep their last ten versions for rollback. | Shipped |
| HTTPS hooks in the pipeline | Signed HTTPS callouts that change what happens: create or reject an inbox for an unknown recipient, accept, reject or quarantine a message before delivery, and allow, deny or hold a send, each with a timeout and a fail-open or fail-closed mode. | Shipped |
| Typed metadata on messages, threads and inboxes | Merge-patch keys onto a message, a thread or an inbox, and declare a key's type so every write to it is validated. | Shipped |