SMS

Send SMS messages, check delivery status, and query message history.

POST/v1/sms/sendapp or admin

Queue an outbound SMS message for delivery.

Request body

Name	Type	Required	Description
`to`	`string`	Required	Recipient phone number in E.164 format (+ followed by 10–15 digits).
`from`	`string`	Required	Sender phone number in E.164 format. Must be an SMS-enabled number on the tenant's RingCentral account.
`body`	`string`	Required	Message text, 1–1600 characters.
`userId`	`string`	Optional	Optional identifier to associate the message with a user in your system.

Request

curl -X POST https://smsgateway-api.onrender.com/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "from": "+15559876543",
    "body": "Hello from Gravity SMS!"
  }'

Success response

202 Accepted

json

{
  "messageId": "msg_a1b2c3d4e5f6",
  "status": "queued"
}

Error responses

400 Missing fields

json

{
  "error": "to, from, and body are required"
}

400 Invalid phone number

json

{
  "error": "to and from must be valid E.164 phone numbers"
}

400 Body too long

json

{
  "error": "body must be 1-1600 characters"
}

401 Unauthorized

json

{
  "error": "Missing or invalid API key"
}

403 Tenant inactive

json

{
  "error": "Tenant suspended or inactive"
}

429 Rate limited

json

{
  "error": "Too many requests"
}

GET/v1/sms/status/:messageIdapp or admin

Get the current status and details of a message.

Path parameters

Name	Type	Required	Description
`messageId`	`string`	Required	Message ID in the format msg_ followed by 12 hex characters.

Request

curl https://smsgateway-api.onrender.com/v1/sms/status/msg_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response

200 OK

json

{
  "messageId": "msg_a1b2c3d4e5f6",
  "status": "sent",
  "rcMessageId": "12345678",
  "error": null,
  "to": "+15551234567",
  "from": "+15559876543",
  "body": "Hello from Gravity SMS!",
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-01T10:00:02.000Z"
}

Status values

queued → sending → sent or failed. Inbound messages have status received.

Error responses

400 Invalid format

json

{
  "error": "Invalid messageId format"
}

404 Not found

json

{
  "error": "Message not found"
}

GET/v1/sms/messagesapp or admin

Query paginated message history with optional filters.

Query parameters

Name	Type	Required	Description
`appId`	`string`	Optional	Filter by app ID. Admin only when filtering other apps.
`tenantId`	`string`	Optional	Filter by tenant ID. Admin only.
`userId`	`string`	Optional	Filter by the userId field set when sending.
`direction`	`string`	Optional	Filter by direction: "outbound" or "inbound".
`status`	`string`	Optional	Filter by status: "queued", "sending", "sent", "failed", or "received".
`from`	`string`	Optional	Filter by sender phone number.
`to`	`string`	Optional	Filter by recipient phone number.
`startDate`	`string`	Optional	ISO 8601 timestamp. Return messages created on or after this date.
`endDate`	`string`	Optional	ISO 8601 timestamp. Return messages created on or before this date.
`page`	`number`	Optional	Page number, starting at 1. Default: 1.
`limit`	`number`	Optional	Results per page. Default: 20, max: 100.

Request

curl "https://smsgateway-api.onrender.com/v1/sms/messages?direction=outbound&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response

200 OK

json

{
  "messages": [
    {
      "messageId": "msg_a1b2c3d4e5f6",
      "jobId": "1",
      "appId": "app_abc123def456abcd",
      "tenantId": "tenant_abc123def456abcd",
      "userId": null,
      "direction": "outbound",
      "to": "+15551234567",
      "from": "+15559876543",
      "body": "Hello from Gravity SMS!",
      "status": "sent",
      "rcMessageId": "12345678",
      "error": null,
      "createdAt": "2026-03-01T10:00:00.000Z",
      "updatedAt": "2026-03-01T10:00:02.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 5
}

Related docs

Sending SMS Guide — Message lifecycle, queue behavior, per-phone rate limits
Receiving SMS Guide — Inbound webhook and WebSocket events
Rate Limits — 40 SMS per phone number per minute