Skip to main content

Reading message status

When you trigger a notification via POST /v1/events/trigger, Nerve responds synchronously with 202 Accepted and an eventId (e.g., evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8).

Because delivery across upstream telcos, push services, and email providers is asynchronous, Nerve provides dedicated endpoints to read message status and inspect chronological event timelines.

Public status API​

Query the live status of any triggered event using your workspace API key:

curl https://api.nervly.io/v1/events/evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer $NERVE_API_KEY"
{
  "event_id": "evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8",
  "status": "DELIVERED",
  "channel": "sms",
  "provider": "termii",
  "recipient": "+2348012345678",
  "attempts": 1,
  "cost_micro_usd": 4200,
  "created_at": "2026-09-11T20:15:00.123Z",
  "updated_at": "2026-09-11T20:15:01.456Z"
}

In TypeScript / Node.js SDK​

Using @nervehq/sdk:

import { Nerve } from '@nervehq/sdk';

const nerve = new Nerve({ apiKey: process.env.NERVE_API_KEY });

const status = await nerve.events.get('evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8');
console.log(`Delivery state: ${status.status} via ${status.provider}`);

Lifecycle statuses​

Every message transitions through a deterministic status machine:

                  ┌───────────────┐
                  │   TRIGGERED   │ (persisted at ingest edge)
                  └───────┬───────┘
                          │
                          ▼
                  ┌───────────────┐
                  │   ENQUEUED    │ (published to JetStream priority stream)
                  └───────┬───────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
  ┌───────────────┐┌───────────────┐┌───────────────┐
  │   DELIVERED   ││    FAILED     ││  SUPPRESSED   │
  │ (provider ack)││(retries spent)││ (opted out /  │
  └───────────────┘└───────────────┘│  DND blocked) │
                                    └───────────────┘
  • TRIGGERED: Ingest edge accepted the request and persisted the initial record before publishing to NATS.
  • ENQUEUED: Published onto the priority broker (NOTIFY_CRITICAL or NOTIFY_BULK).
  • DELIVERED: The delivery adapter received an affirmative 2xx acknowledgment from the upstream provider.
  • FAILED: Dispatch exhausted all providers and all exponential retries; published to DLQ.
  • SUPPRESSED: Delivery was intentionally suppressed without provider contact due to subscriber channel preferences or NCC 2442 DND marketing restrictions.

Event timeline in the dashboard​

In the Nerve dashboard at https://app.nervly.io/messages:

  • Filter messages by status, channel, subscriber, or date range.
  • Click any message to open the Message Drawer, revealing the complete chronological delivery timeline in order, with exact timestamps, provider responses, and error codes.
Outbound webhooks

Nerve supports polling via GET /v1/events/{eventId} and dashboard inspection at launch. Automated outbound webhooks delivering status callbacks to your servers are scheduled for Month 6 (ADR-010).

Next​