Events queue

Fetch your events when it suits you, with no public address to run. Useful behind a firewall, or from a scheduled job.

How it works

Turn on the events you want under Admin → API → Events. Every event of those types goes into your organisation's queue.
Fetch events gives you a batch, oldest first, and hides it from other fetches for 60 seconds.
Acknowledge each event you handled with its receipt. It is removed. Anything not acknowledged within 60 seconds comes back, with attempt one higher.
Events wait up to 7 days, or 30 on the Business plan.

Several workers can fetch at once: a batch goes to one of them only. With types, a worker takes only those types and leaves the rest for others. A receipt is good only for the fetch that gave it, so a slow worker can't remove an event another worker has since taken.

With the Node SDK

For a long-running process, listen fetches as events arrive and calls your handler for each one. An event is acknowledged only when the handler finishes without throwing; if it throws, the event comes back after 60 seconds.

const listener = torvath.events.listen({ types: ["email.bounced", "email.complained"] }, async (event) => {
  await markAddressBad(event.recipient, event.reason);
});

// when your app shuts down
await listener.stop();

No long-running process? Use pull from a scheduled job instead.

With plain HTTP

curl

# Take up to 50 events, waiting up to 20 seconds for some to arrive
curl "https://api.torvathmail.com/v1/events?wait=20" -H "Authorization: Bearer $TORVATH_API_KEY"

# Remove the ones you handled
curl https://api.torvathmail.com/v1/events/ack \
  -H "Authorization: Bearer $TORVATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "receipts": ["4812.Hq8ZpL2vXk9mR3tW"] }'

Webhooks or the queue?

Both carry the same events, and you can use both. Webhooks arrive within seconds with nothing to run, but need an address on the internet. The queue needs no address, and you choose when to take events.