Skip to main content

Quickstart

Send one notification, verify it was accepted, and check its delivery status. Walkable by a stranger in under ten minutes.

1. Sign up and get an API key​

  1. Open app.nervly.io and sign up with your email or Google OAuth.
  2. An initial workspace is created automatically on signup.
  3. Go to Developers in the sidebar.
  4. Click Create API Key. Choose Test for sandbox evaluation or Live for real dispatch.
  5. Copy your key (nerve_sk_test_... or nerve_sk_live_...).
The key is shown once

API keys are hashed with SHA-256 before storage; the plaintext token is never recoverable from the dashboard. Store it in your secret manager.

2. Connect a provider (or use Test Mode)​

  • Test Mode: If you use a nerve_sk_test_... key, no external provider configuration is needed! Nerve automatically short-circuits provider dispatch, records normal message timelines, and returns synthetic success without incurring telco charges.
  • Live Mode: Go to Providers in the dashboard and add your credentials for Termii, Postmark, SendGrid, or any supported provider. Click Test Connection to verify your credentials.

3. Verify gateway reachability​

Confirm you can reach the edge gateway without authentication:

curl https://api.nervly.io/v1/health
{
  "status": "OK",
  "service": "nerve-gateway",
  "version": "0.1.0",
  "environment": "production",
  "uptime_seconds": 86400,
  "nats_connected": true
}

4. Send a notification​

Using cURL​

curl -X POST https://api.nervly.io/v1/events/trigger \
  -H "Authorization: Bearer $NERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-confirmed",
    "to": {
      "subscriberId": "sub_4920a",
      "phone": "+2348012345678",
      "email": "customer@example.com"
    },
    "payload": {
      "orderId": "ORD-94102",
      "amount": "15,000 NGN"
    }
  }'
{
  "eventId": "evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8",
  "status": "QUEUED",
  "channel": "sms",
  "priority": "NORMAL",
  "idempotencyKey": null,
  "timestamp": "2026-09-11T21:00:00.000Z"
}

Or using the TypeScript SDK​

Install @nervehq/sdk:

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

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

const result = await nerve.events.trigger({
  name: 'order-confirmed',
  to: {
    subscriberId: 'sub_4920a',
    phone: '+2348012345678',
    email: 'customer@example.com',
  },
  payload: {
    orderId: 'ORD-94102',
    amount: '15,000 NGN',
  },
});

console.log(`Accepted with Event ID: ${result.eventId}`);

5. Check delivery status​

Query the live delivery status of your event:

curl https://api.nervly.io/v1/events/evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer $NERVE_API_KEY"
{
  "event_id": "evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8",
  "event_name": "order-confirmed",
  "subscriber_id": "sub_4920a",
  "status": "DELIVERED",
  "channel": "sms",
  "provider": "termii",
  "priority": 2,
  "attempts": 1,
  "cost_micro_usd": 4200,
  "test_mode": false,
  "variables_keys": ["orderId", "amount"],
  "created_at": "2026-09-11T21:00:00.123Z",
  "updated_at": "2026-09-11T21:00:01.456Z"
}

Or view the event visually in app.nervly.io/messages to see the delivery timeline.

6. Make the call safe to retry​

Add an Idempotency-Key header with a unique business identifier (e.g. order-ORD-94102):

curl -X POST https://api.nervly.io/v1/events/trigger \
  -H "Authorization: Bearer $NERVE_API_KEY" \
  -H "Idempotency-Key: order-ORD-94102" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If a network timeout occurs and your application retries, Nerve returns the cached response with 200 OK and prevents duplicate customer notifications.

Next steps​