Gravity SMS Docs

Sending SMS

Send outbound SMS messages through the gateway. Messages are queued for asynchronous delivery via RingCentral with automatic retries on failure.

When to use this

  • Send transactional or notification SMS to end users.
  • Send messages from any SMS-enabled RingCentral phone number assigned to your tenant.

Prerequisites

  • A valid API key (Authentication).
  • An active RingCentral connection for the tenant (Connecting RingCentral).
  • The "from" phone number must be SMS-enabled in RingCentral and assigned to your account.

How it works

  1. Queue — A POST /v1/sms/send request validates the payload and places the message in a background queue. The API responds immediately with 202 Accepted and a messageId.
  2. Send — A background worker picks up the job, resolves the RingCentral extension for the "from" number, and calls the RingCentral SMS API.
  3. Status update — On success the message status changes to sent. On failure it changes to failed with an error description.
  4. Notification — A sms_status event is published to WebSocket subscribers after each status change.

Message lifecycle

StatusMeaning
queuedMessage accepted and waiting in the send queue.
sendingWorker has picked up the job and is sending via RingCentral.
sentRingCentral accepted the message for delivery.
failedDelivery failed after all retry attempts. The error field contains the reason.

Phone number format

Both to and from must be in E.164 format: a + followed by the country code and subscriber number (9–15 digits total).

Valid E.164 examples
+15551234567    (US)
+442071234567   (UK)
+61412345678    (AU)

Example

Send a message
curl -X POST https://smsgateway-api.onrender.com/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15559876543",
    "from": "+15551234567",
    "body": "Your verification code is 123456"
  }'
202 Accepted
json
{
  "messageId": "msg_a1b2c3d4e5f6",
  "status": "queued"
}

Check delivery status

Poll for status
curl https://smsgateway-api.onrender.com/v1/sms/status/msg_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
json
{
  "messageId": "msg_a1b2c3d4e5f6",
  "status": "sent",
  "rcMessageId": "mock_abc123def456",
  "error": null,
  "to": "+15559876543",
  "from": "+15551234567",
  "body": "Your verification code is 123456",
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-01T10:00:01.000Z"
}

Retries and rate limits

  • Automatic retries — Failed send attempts are retried up to 3 times with exponential backoff.
  • Per-phone rate limit — Each "from" number is limited to 40 messages per minute. If exceeded, the job is delayed by 5 seconds and retried automatically.
  • API rate limit — API keys are subject to per-key rate limits (Rate Limits).

Message body limits

The body field must be between 1 and 1,600 characters. Messages exceeding this limit are rejected with a 400 error.

Optional fields

The userId field is an optional string you can include to associate the message with a user in your system. It is stored with the message and returned in queries, but has no effect on delivery.

Common errors

StatusErrorCause
400to, from, and body are requiredOne or more required fields missing.
400to and from must be valid E.164 phone numbersInvalid phone number format.
400body must be 1-1600 charactersMessage body empty or too long.
403Tenant suspended or inactiveThe tenant associated with this API key is not active.
If a message reaches failed status, the error field on the message object describes the specific failure reason, such as an unregistered phone number or a RingCentral connection issue.

Related docs