API Overview & Managing API Keys

Integrate Rayo SMS directly into your ERP, CRM, e-commerce store, booking platform, or custom application using our fast and reliable RESTful HTTP API.

Interactive API Reference

For complete request/response schemas, status codes, error payloads, and code examples, consult the Full Rayo SMS API Reference at https://api-docs.rayosms.com.

---

API Base Endpoint

All HTTP API requests must be made over HTTPS to the following base URL:

https://api.rayosms.com/v1

---

Managing API Keys

You can manage your API credentials in the Web Application by navigating to Advanced -> Settings -> API Keys (/settings/api_keys).

• Automatic Initial Key: An initial API key is automatically generated for you as soon as your account is created.
• Up to 25 API Keys per Account: Click Generate API Key to create additional keys (up to 25 keys maximum). Using separate keys is recommended for isolating production, staging, and individual microservices or third-party integrations.
• Lifecycle Controls: You can Activate, Deactivate, or Delete individual API keys at any time without affecting your other active keys.

---

Authentication

Every API request must include an active API key in the HTTP Authorization header over HTTPS:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Account & Key Must Both Be Active

For an API request to succeed, both your Rayo SMS user account and the specific API key used in the Authorization header must be Active. If a key is deactivated, requests using it will be rejected immediately.

---

Core Endpoints Summary

Below is an overview of the primary Rayo SMS API v1 endpoints. Visit the Full Rayo SMS API Reference for detailed parameter specifications and sample payloads.

POST /v1/send_sms — Send Single, Bulk, or Scheduled SMS

Dispatches an SMS message to one or more recipient mobile numbers and/or Contact Groups.

• Recipients & Groups: Pass an array of mobile numbers, group IDs, or both (with automatic deduplication and suppression of contacts marked Invalid).
• Scheduling (scheduledAt): Optionally schedule the message for future delivery by providing an ISO-8601 timestamp.
• Idempotency & Tracking (clientRequestId): Supply your own unique reference ID to correlate status checks and webhook callbacks.
• Webhook Callbacks: Enable delivery status callbacks per request.
• Free Sandbox Testing (simulateSendFlag): Set simulateSendFlag: true to validate your request payload and integration end-to-end while consuming 0 credits and without delivering real SMS handsets.

GET /v1/balance_in_credits — Check Credit Balance

Returns your account’s current available SMS credit balance as an integer so you can monitor usage programmatically.

GET /v1/check_status — Query Delivery Status

Retrieves the current processing status and per-recipient delivery reports of a previously submitted SMS request by querying either your custom clientRequestId or the Rayo SMS smsServerRequestId.

DELETE /v1/sms_request_schedules/:id — Cancel a Scheduled SMS

Cancels and deletes a pending scheduled SMS request (scheduledAt) before its scheduled execution time, refunding the reserved credits back to your available balance.