Skip to main content

How Nervly delivers a notification

This page explains what happens between your API call and a recipient's phone, so you can reason about latency, reliability, and cost. It is the why behind the behaviour the guides teach you to use.

The path of one notification​

The 202 you receive means Nervly has durably accepted responsibility for the event, not that the recipient has it. Delivery outcomes are recorded and queryable, and arrive later on your receipt endpoint.

Channel selection​

You supply one or more contact details (phone, email, device tokens). Nervly resolves them to a channel using the event's priority: urgent events take the most reachable channel, everything else the cheapest that works. You can override the choice per request, and the worker may still fail over to a different channel if every provider on the chosen one rejects the message. The delivery record always reports what actually happened.

Failover and circuit breaking​

Providers fail — a carrier goes down, a region degrades, an API key expires. Nervly treats that as normal:

  • Each (workspace, provider) pair has an independent circuit breaker. When a provider starts failing, its breaker opens and traffic is routed to the next configured provider instead of hammering a dead one.
  • Breaker state is shared across workers, so one worker discovering a failure protects the whole fleet.
  • Breakers are strictly per-tenant: one workspace's provider problems never degrade another's delivery.

Isolation and safety​

  • Every record belongs to exactly one workspace, enforced in the database itself, not only in application code.
  • API keys are compared in constant time and stored only as a hash; provider credentials are encrypted at rest with per-workspace keys.
  • Outbound content is sanitised per channel so that a value interpolated from your payload cannot inject control characters or markup into SMS, email, push, or voice traffic.
  • Nigerian marketing traffic is screened against DND 2442 and fails closed, so a compliance failure suppresses delivery rather than risking a regulatory fine; transactional and OTP traffic fails open so critical messages still get through.

Next​