Skip to main content

📖 API Reference Overview

The Sendly API is organized around REST principles. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL​

All API requests should be made to:

https://sendly.live/api
🔒 HTTPS Required

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authentication​

The Sendly API uses API keys to authenticate requests. Include your API key in the Authorization header:

Authorization: Bearer sl_live_your_api_key

→ Learn more about authentication

Content Type​

All requests should include the Content-Type header:

Content-Type: application/json

API Versions​

The current API version is v1. All endpoints are prefixed with /v1/.

https://sendly.live/api/v1/send

Response Format​

All responses are returned as JSON and include:

  • Success responses - HTTP 2xx with response data
  • Error responses - HTTP 4xx/5xx with error details
Successful Response Example
{
  "messageId": "msg_2cY8vH8LkQx3J5oP",
  "status": "queued",
  "from": "+18005551234",
  "to": "+1234567890",
  "text": "Hello from Sendly!",
  "routing": {
    "numberType": "toll-free",
    "coverage": "high",
    "reason": "smart-routing"
  },
  "cost": {
    "amount": 0.0075,
    "currency": "USD"
  }
}
Error Response Example
{
  "error": "validation_error",
  "message": "Invalid phone number format",
  "code": "invalid_phone_number",
  "statusCode": 400
}

Endpoints Overview​

📱 Messaging​

POST Send SMS/MMS
GET Get Message Status
GET List Messages

⚡ Rate Limits​

GET Get Rate Limits
GET Live Stats

🔗 Webhooks​

POST Configure Webhooks
Real-time delivery notifications

📊 Analytics​

GET Usage statistics
GET Delivery reports
GET Cost analysis

HTTP Status Codes​

Sendly uses conventional HTTP response codes to indicate the success or failure of an API request:

CodeStatusDescription
2xxSuccessRequest succeeded
200OKRequest succeeded
201CreatedResource created successfully
4xxClient ErrorError with the request
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions
404Not FoundResource not found
429Too Many RequestsRate limit exceeded
5xxServer ErrorError on Sendly's end
500Internal Server ErrorSomething went wrong
503Service UnavailableTemporary service outage

Error Handling​

All error responses include detailed information:

Detailed Error Response
{
  "error": "validation_error",
  "message": "Invalid phone number format for 'to' field",
  "code": "invalid_phone_number",
  "statusCode": 400,
  "field": "to",
  "documentation": "https://sendly.live/docs/api-reference/errors"
}

Common Error Types​

validation_error​

HTTP 400 - Request parameters are invalid
Common causes: Invalid phone numbers, missing required fields

authentication_error​

HTTP 401 - API key is invalid or missing
Common causes: Wrong API key, missing Authorization header

rate_limit_exceeded​

HTTP 429 - Too many requests
Common causes: Exceeding rate limits, need to implement backoff

api_error​

HTTP 5xx - Server-side error
Common causes: Temporary service issues, maintenance

→ Complete error reference

Rate Limiting​

Sendly implements rate limiting to ensure fair usage:

  • Default limit: 100 requests per minute
  • Burst limit: 1000 requests per hour
  • Headers included: X-RateLimit-Limit, X-RateLimit-Remaining
Rate Limit Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

→ Learn more about rate limiting

Pagination​

List endpoints support pagination using cursor-based pagination:

Paginated Request
GET /v1/messages?limit=50&cursor=msg_abc123
Paginated Response
{
  "data": [
    {
      "messageId": "msg_abc123",
      "status": "delivered",
      // ... message data
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "msg_def456",
    "previousCursor": null,
    "totalCount": 1250
  }
}

Idempotency​

Sendly supports idempotency for safe retries. Include an Idempotency-Key header:

Idempotent Request
curl -X POST https://sendly.live/api/v1/send \
  -H "Authorization: Bearer sl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique_key_123" \
  -d '{
    "to": "+1234567890",
    "text": "Hello world!"
  }'

SDKs and Libraries​

Official SDKs handle authentication, error handling, and retries automatically:

npm install @sendly/node
import { SendlyClient } from '@sendly/node';

const sendly = new SendlyClient({
  apiKey: 'sl_live_your_api_key'
});

Node.js SDK Documentation →

Interactive Testing​

API Playground​

Test all endpoints directly in your browser with live examples:

🎮 Open API Playground →

Postman Collection​

Import our complete Postman collection for easy testing:

📦 Download Postman Collection →

OpenAPI Specification​

Access our complete OpenAPI 3.0 specification:

📄 View OpenAPI Spec →

Quick Examples​

Send Basic SMS​

cURL
curl -X POST https://sendly.live/api/v1/send \
  -H "Authorization: Bearer sl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "text": "Hello from Sendly!"
  }'

Send MMS with Media​

Node.js
const result = await sendly.sms.send({
  to: '+1234567890',
  text: 'Check out this image!',
  mediaUrls: ['https://example.com/image.jpg']
});

Get Message Status​

Python
message = client.sms.get('msg_abc123')
print(f'Status: {message.status}')

Support & Resources​

💡 Ready to Get Started?

Start with our 5-minute quick start guide or jump straight into the API playground to test endpoints.

Next Steps​