Email jobs

Backed by: @pithy-sh/email. Scopes: email:jobs:read · email:jobs:retry · email:suppressions:read · email:suppressions:write · email:suppressions:delete.

Silent email failure costs a signup, which is why this pane exists.

The statuses

Each is the job model’s own. Bounces and suppression is why a send stops, deliverability is how to keep it from happening, and feedback tracking is what the opens and clicks are.

pendingImmediate, awaiting dispatch
scheduledA future send time
sendingIn flight
sentSucceeded
failedExhausted its retries
suppressedSkipped — the address is on the list
bouncedReported undeliverable
undispatchedThis composition binds no send Workflow
canceledWithdrawn before sending

undispatched is a configuration fact, not a transient one. Nothing was started and nothing is coming while that holds — and the scheduler claims those rows as soon as a host Worker exists.

A status that says your wiring is incomplete is worth more than a pending row that quietly never moves.

The send log filters on your Worker, over every job rather than the page on screen: Status, any of the nine above, Template, from the templates the jobs read name, and Category, transactional or marketing. It reads a page at a time. The overview is how the filter panel works.

Retrying one

Send again is on a failed job’s record, and it asks first, because it mails a real person. Only a failed job is sent again: any other job says which status it is in rather than spending a call to be told. It is part of Solo; below it, the act is drawn locked and says what the plan buys, and your Worker still retries on any plan.

email:jobs:retry, and the retry sets the batch id in the same statement that makes the row queryable again — because a row naming an instance that is not working it turns the scheduler’s veto into a lie in one of two directions.

The suppression list

Four reasons, and two of them block everything:

Blocks
hard_bounceEverything
complaintEverything
unsubscribeElective mail only
manualWhat you set it for

Somebody who unsubscribed from your newsletter has not stopped being able to sign in.

The Suppressions pane

The send log masks the recipient, so no job can name an address to block. The list is its own pane, read live with email:suppressions:read: each address in full, why it is blocked, whether the block is still in force, which environment’s job tripped it, and when it lifts.

Its filters go to your Worker too: Reason, one of the four, and Standing, active or lifted. Address is a lookup, not a search: type the whole address and it is sent in the body of POST /email/suppressions/lookup, never in a URL, so the answer is that one address or nothing, held to the reason and standing chosen beside it. A Worker older than @pithy-sh/email 0.10 has no lookup, and the field is drawn locked, saying so; nothing is sent in a URL instead. The list reads a page at a time.

Block again re-arms a block that has lifted, and is recorded as manual, because the dashboard observed no bounce. Unblock lets every environment mail the address again and forgets why it was blocked. It is a deletion, so it is an owner’s, and an admin sees it locked and marked for the owner. Both are part of Solo, and both ask first.

Removing a suppression is a POST with a body

Not a path parameter.

An address in a path is an address in every access log, proxy, trace and referrer between the client and the Worker.

The suppression database is shared across environments

Deliberately — an unsubscribe has to apply everywhere, and somebody who opted out in production has not agreed to receive staging’s mail.

One thing this pane cannot show you everywhere

Bounce attribution is platform-limited. There is one inbound Worker per domain, and it is production’s.

So feature and staging environments see their own opens, clicks and unsubscribes — but not asynchronously-routed bounces.

email/suppressed is not a failure to fix

The address is on the opt-out list, and that is the list working.

ESC