SMS Messaging

1. Prerequisites & Phone Format (E.164)

Before sending SMS notifications:

1. Twilio Provider: Configure your Twilio Account SID, Auth Token, and Sender Phone Number or Messaging Service SID in the Sendrin Console.
2. Active Event Key: Create and publish an event (e.g. order_shipped) with an SMS template containing your variable placeholders (e.g. {{customer_name}}, {{tracking_code}}).

All mobile phone numbers must strictly comply with the international E.164 standard:

• Include the country code with a leading + sign.
• Omit dashes, spaces, and leading zeroes.
• Examples: +14155552671 (US), +442071838750 (UK), +919876543210 (India). Numbers failing this format return 422 invalid_recipient.

2. Dispatching an SMS (POST /api/v1/notifications)

Sendrin decouples event triggering from transport. Pass your event_key, the target phone in the recipient object, and template variables in data. Always include a unique Idempotency-Key header to safely retry without duplicate sends.

curl -X POST "https://api.gns.iitdeveloper.com/api/v1/notifications" \
-H "Authorization: Bearer gns_live_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7b3e2189-9a28-48b0-a541-6945df84b802" \
-d '{
  "event_key": "order_shipped",
  "channel": "sms",
  "recipient": {
    "phone": "+14155552671"
  },
  "data": {
    "customer_name": "Alex",
    "tracking_code": "TRK-98174",
    "eta": "today between 2:00 PM and 4:00 PM"
  }
}'

3. Asynchronous Acceptance Response (202 Accepted)

The API responds with 202 Accepted. This confirms that the request passed schema validation and was safely committed to the transactional outbox for background delivery workers. It does not indicate instant carrier delivery.

4. Delivery Callbacks vs Outbound Webhooks

• Twilio Provider Callbacks: Twilio posts status updates (sent, delivered, undelivered, failed) back to POST /api/v1/callbacks/twilio/sms. Sendrin verifies Twilio HMAC signatures and transitions the internal state machine.
• Customer Outbound Webhooks: To receive real-time delivery confirmations in your application backend, subscribe an endpoint under Outbound Webhooks. Sendrin will dispatch signed JSON payloads (notification.delivered or notification.failed).

5. Common Error Responses