Skip to main content

Priorities & routing

Priority does two things: it puts the event on a separate broker lane, and for email it changes which provider is tried first.

Setting priority​

Send the X-Priority-Override header on POST /v1/events/trigger:

curl -X POST https://api.nervly.io/v1/events/trigger \
  -H "Authorization: Bearer $NERVE_API_KEY" \
  -H "X-Priority-Override: CRITICAL" \
  -H "Content-Type: application/json" \
  -d '{ "name": "otp-login", "to": { "subscriberId": "user_8f21c", "phone": "+2348012345678" } }'
ValueUse it for
CRITICALOTPs, security alerts, fraud holds — anything blocking a user
HIGHTransaction confirmations, failed payments
NORMALDefault. Receipts, status updates
LOWDigests, marketing, anything batchable

The header is case-insensitive. Anything unrecognised silently becomes NORMAL — there is no validation error for a typo, so check the priority field in the response if it matters:

{
  "eventId": "evt_9c4f1a...",
  "status": "QUEUED",
  "priority": "CRITICAL",
  "timestamp": "2026-08-28T09:15:04.221Z"
}

What priority actually changes​

The broker subject. Every accepted event is published to NATS JetStream on:

notify.{channel}.{priority}.{subscriberId}

For example notify.sms.critical.user_8f21c. Because priority is part of the subject, critical traffic can be consumed by dedicated workers and is not queued behind a million-row digest job.

The email provider. CRITICAL and HIGH email tries Postmark first; NORMAL and LOW tries SendGrid first. See Channels & providers.

The channel. Urgent events take the most reachable channel, routine events the cheapest — so the same recipient gets SMS for a CRITICAL event and email for a NORMAL one. This is the single biggest cost lever you have. See Channels & providers.

Priority does not change SMS provider order, and does not bypass rate limits or subscriber preferences. A CRITICAL event to a subscriber who has turned off SMS is still suppressed — see Subscriber preferences.

The subject's channel is the channel Nerve chose​

The gateway and the worker resolve the channel with the same rules, so notify.email.normal.… means the event was routed as email. The trigger response reports the same value as channel.

It is still not a guarantee of the delivered channel

If every provider on the chosen channel rejects the message, the worker falls back to the next eligible channel — the event stays on its original subject while going out by a different route. For what actually carried a message, read channel from the delivery receipt, not from the subject.

The full path of an event​

The gateway waits for the broker's ack before returning, so a 202 means the event is durable. Everything after the ack is asynchronous.

Next​