Questions · Updated 2026-09-28

How do I control account notifications?

Control account notifications with PATCH /notifications/preferences, which turns each notification type on or off per channel — the console bell (in_app) or email. GET /notifications lists the open conditions, and POST /webhooks is the machine channel.

Control account notifications with PATCH /notifications/preferences. Its summary is "Turn a notification type on or off per channel. The gate is the type — there is no severity to mute instead." The two channels are in_app, the bell in the console, and email. GET /notifications/preferences returns the current setting for every type, and its summary says "A type with no stored row is on for both." In the console the same switches are under Settings → Notifications.

What the account is told about

Each preference row is a type with in_app and email booleans. The types the API offers are budget_exhausted, kill_switch_engaged, approvals_pending, trust_state_changed, webhook_endpoint_disabled, domain_verification_lost, domain_verified, appeal_decided, dmarc_unaligned_source, api_key_leaked, onboarding, welcome, billing and support. Send only the types you want to change; a field you leave out keeps its value.

curl -sS -X PATCH https://api.agentisend.com/notifications/preferences \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"preferences":[]}'
200
{
  "preferences": []
}
Response

Two rules in the mailer decide who gets the email. Operational alerts go to every person on the account; welcome and billing mail go to owners only. billing ignores the email switch, because billing mail is transactional: a preference cannot silence a failed payment or a plan ending. Turning support email off stops the mails Support describes; the request stays in the console. Every change to a preference writes a notification.preference_changed row to GET /audit-log, so who turned the budget alert off is on record.

Reading and clearing the bell

GET /notifications — "Conditions this account should know about. Open rows are live; resolved ones ended. One row per condition, counted, never one per re-fire." Filter with state (open or resolved) and unread. Each row has title, body, console_path (the screen that fixes it), occurrences, first_seen_at, last_seen_at, read_at and resolved_at.

POST /notifications/{id}/read marks one row: "Reading it never resolves it — the condition ends the row, not the reader." A budget row resolves when the period resets or the budget is raised, not when you read it. POST /notifications/read with no ids marks every open row — the summary calls it the bell's "Mark all read".

These routes are management calls. A sending_access key is refused with restricted_api_key; use a full_access key or the console session.

The machine channel

Notification preferences change what people see and receive. They do not change webhooks. Register an endpoint with POST /webhooks and subscribe to the event types your software should act on: limit.warning and limit.exceeded for budgets and the plan inclusion, domain.failed and domain.verified for DNS, agent.approval_requested for a held send, agent.killed for the kill switch, and trust.warning, trust.throttled and trust.paused for standing. Every type is in the event catalogue, and Webhooks covers signing and retries. A webhook delivery is one event; the bell folds re-fires of one condition into a single row and counts them in occurrences.

Next