Skip to main content

Delivery receipts

A 202 Accepted from POST /v1/events/trigger indicates that Nerve accepted the notification and durably enqueued it onto JetStream. Delivery receipts determine what happened next.

Checking delivery status​

At launch, Nerve supports two primary methods for customers to inspect delivery status:

1. Polling via API & SDK​

You can query any event by its ID using the public status endpoint:

curl https://api.nervly.io/v1/events/evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer $NERVE_API_KEY"

Or with the official TypeScript SDK (@nervehq/sdk):

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

const nerve = new Nerve({ apiKey: process.env.NERVE_API_KEY });
const receipt = await nerve.events.get('evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8');

console.log(`Status: ${receipt.status}, Provider: ${receipt.provider}, Cost: $${receipt.cost_micro_usd / 1e6}`);

2. Live stream in the dashboard​

In app.nervly.io/messages, your team can search, filter, and inspect deliveries with real-time status badges (DELIVERED, FAILED, SUPPRESSED). Clicking any message opens the drawer to display the chronological delivery timeline in order.

Outbound webhooks roadmap

Nerve provides immediate status polling via GET /v1/events/{eventId}. Outbound webhooks pushing delivery status events directly to your HTTP endpoints are scheduled for Month 6 (ADR-010). We intentionally deferred outbound webhooks to ensure proper signature rotation, dead-letter retry queues, and replay protection without rushing the launch.

Upstream provider delivery receipts​

When downstream providers (Termii, SendGrid, Postmark, etc.) deliver an SMS or email, they send asynchronous webhooks back to Nerve:

https://api.nervly.io/v1/webhooks/{provider}

Nerve normalises each provider’s proprietary payload into a standardized receipt event:

FieldMeaning
event_idNerve event identifier
message_idProvider’s external message identifier
recipientSanitized destination (phone or email)
statusDelivery state (DELIVERED, FAILED, SEEN, CLICKED)
channelChannel used (sms, email, whatsapp, push)
cost_micro_usdDelivery cost in micro-USD ($0.000001)

Durability and telemetry​

After dispatch, the worker records delivery state and telemetry:

  • It updates the message's status (DELIVERED, FAILED, SUPPRESSED), attempt count, provider, and final channel.
  • It appends an immutable timeline step for each state transition, including error diagnostics.
  • It aggregates daily message counts and costs per workspace, channel, and provider so analytics queries do not scan the full message history.

Every record is scoped to your workspace; none of it is visible to another tenant.

Next​