Skip to main content

Reading message status

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

Because delivery across upstream telcos, push services, and email providers is asynchronous, Nervly 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 $NERVLY_API_KEY"
{
  "event_id": "evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8",
  "event_name": "order-confirmed",
  "subscriber_id": "sub_4920a",
  "status": "DELIVERED",
  "channel": "sms",
  "provider": "termii",
  "priority": 3,
  "attempts": 1,
  "cost_micro_usd": 5000,
  "test_mode": false,
  "variables_keys": ["orderId", "amount"],
  "created_at": "2026-09-11T20:15:00.123Z",
  "updated_at": "2026-09-11T20:15:01.456Z"
}

In TypeScript / Node.js SDK​

Using @nervly/sdk:

import { Nervly } from '@nervly/sdk';

const nervly = new Nervly({ apiKey: process.env.NERVLY_API_KEY });

const status = await nervly.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 Nervly 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

Nervly supports polling via GET /v1/events/{eventId} and dashboard inspection at launch. Direct outbound webhooks delivering status callbacks to your own servers are not part of the launch surface — they are scheduled for Month 6 or later (product sequencing; ADR-010 covers deploy topology, not webhooks). At launch, real delivery events reach your machine through the local CLI's forwarding tunnel, nervly forward webhooks, which dials out to a Nervly-operated relay and re-signs locally — a consumer of the delivery stream, not a second webhook product. See Delivery receipts for the signature schemes Nervly enforces on the inbound provider callbacks it does accept today.

Next​