Complete endpoint specification, parameters, and response schemas for the Sendrin REST API.

Sendrin REST API Reference

All requests to the Sendrin API are served over HTTPS and expect/return JSON payloads.

Production Base URL: https://api.sendrin.com
UAT / Staging Base URL: https://api.uat.sendrin.com
Current API Version: v1 (/api/v1/...)

Global Headers

Header	Required	Example / Format	Description
`Authorization`	Yes	`Bearer gns_live_sk_...`	Application secret key or Keycloak JWT session.
`Content-Type`	Yes (for POST/PATCH)	`application/json`	Request payload format.
`Idempotency-Key`	Required for notifications	`9b1deb4d-3b7d-4bad-...`	Prevents duplicate sends on network retries.

Transactional OTP Endpoints

1. Send OTP Code

POST /api/v1/otp/send

Generates and delivers a cryptographically secure one-time password via email, SMS, or WhatsApp.

Request Body Parameters

Parameter	Type	Required	Description
`channel`	`string`	Yes	Destination channel: `email`, `sms`, or `whatsapp`.
`recipient_email`	`string`	Conditional	Required when `channel='email'`. Target email address.
`recipient_phone`	`string`	Conditional	Required when `channel='sms'` or `whatsapp`. E.164 phone (e.g. `+14155552671`).
`purpose`	`string`	Optional	Verification purpose: `login`, `signup`, `verification`, `password_reset` (default: `login`).
`code_length`	`integer`	Optional	Number of digits (default: `6`, options: 4 to 8).
`ttl_seconds`	`integer`	Optional	Expiration time in seconds (default: `600`, max: 3600).
`code`	`string`	Optional	Caller-provided custom code (requires `otp:custom_code` permission).

Response200 OK

{
  "otp_id": "otp_6cbdf2fdbf4b",
  "status": "sent",
  "channel": "email",
  "expires_at": "2026-09-26T19:08:07Z",
  "ttl_seconds": 600,
  "purpose": "login",
  "remaining_credits": 995
}

2. Verify OTP Code

POST /api/v1/otp/verify

Validates a user-submitted code against an active session.

Request Body Parameters

Parameter	Type	Required	Description
`channel`	`string`	Yes	Destination channel: `email`, `sms`, or `whatsapp`.
`recipient_email`	`string`	Conditional	Required when `channel='email'`. Target email address.
`recipient_phone`	`string`	Conditional	Required when `channel='sms'` or `whatsapp`. E.164 phone.
`code`	`string`	Yes	The OTP code entered by the user.
`purpose`	`string`	Optional	Verification purpose (default: `login`).

Response200 OK

{
  "verified": true,
  "message": "Code verified successfully.",
  "verification_token": "vtok_ccfed7ca0edeb77ece1842d833c4a9b1c2bb5ed8a39f2960637ac30a49f8c977",
  "verified_at": "2026-09-26T18:58:09Z",
  "remaining_attempts": null
}

3. Check OTP Credits Balance

GET /api/v1/otp/credits

Returns the current workspace OTP credit balance and active subscription plan.

Response200 OK

{
  "tenant_id": "tnt_b3d379180ec64f25b90b07b29da16efc",
  "credits_balance": 995,
  "plan": "free"
}

Core Notification Endpoints

4. Dispatch Notification

POST /api/v1/notifications

Dispatches a templated notification across email, SMS, WhatsApp, or in-app channels.

Required Headers

Authorization: Bearer <app_api_key>
Idempotency-Key: <unique_string>
Content-Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
`event_key`	`string`	Yes	Registered event key (e.g. `order.placed`, `user.welcome`).
`channel`	`string`	Yes	Destination channel: `email`, `sms`, `whatsapp`, `in_app`.
`recipient`	`object`	Yes	Recipient object, e.g. `{"email": "[email protected]"}`.
`data`	`object`	Yes	Dynamic variables interpolated into the event template schema.
`locale`	`string`	Optional	Locale code (defaults to application default locale).
`priority`	`integer`	Optional	Delivery priority (1-10, default: 5).

Response202 Accepted

{
  "status": "accepted",
  "id": "notif_01J7K3X9AB0C1D2E",
  "application_id": "app_61fd23f26f6945fe9291f21bbaee65ed",
  "event_key": "user.welcome",
  "channel": "email"
}

Custom Sending Domain Endpoints

5. List Custom Domains

GET /api/v1/tenants/{tenant_id}/domains

Returns all custom sending domains configured for the current workspace with SPF, DKIM, DMARC, and Return-Path verification states.

6. Add Custom Domain

POST /api/v1/tenants/{tenant_id}/domains

Registers a new custom sending domain and generates cryptographic DKIM and DNS verification instructions.

Request Body Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Fully qualified root domain or subdomain (e.g. `vanshveda.com` or `mail.vanshveda.com`).

7. Verify Domain DNS Records

POST /api/v1/tenants/{tenant_id}/domains/{domain_id}/verify

Triggers immediate authoritative DNS resolution checks across SPF, DKIM, DMARC, and Return-Path records.

Delivery Activity Endpoints

8. Query Activity Feed

GET /api/v1/activity

Queries the paginated, privacy-masked delivery timeline across all applications and channels.

Query Parameters

limit (integer, default: 50, max: 200)
offset (integer, default: 0)
channel (email, sms, whatsapp, in_app)
status (queued, sent, delivered, failed, verified)
search (string, recipient or subject filter)

9. Retry Delivery

POST /api/v1/activity/{id}/retry

Re-enqueues a previously failed dispatch for execution.

REST API Reference

On this page