API Documentation

API Reference

Complete reference for the Simly Public API. All endpoints use the /v1/ prefix.

v1.0.0•OAS 3.0

Authentication

All API requests must include your API key in the Authorization header using the Bearer scheme:

HTTP Header

Authorization: Bearer sk_live_your_api_key_here

sk_test_*Test Keys

Use test keys for development and testing. Messages are simulated and no real SMS is sent.

sk_live_*Live Keys

Use live keys for production. Messages are sent via your connected Android devices.

Base URL

https://server-simly.servelink.space/v1

All API endpoints are relative to this base URL.

Messages

Send and retrieve SMS messages

POST/v1/messages

Send an SMS message

Send an SMS message to a phone number. The message will be queued for delivery via one of your connected Android devices. Use sk_test_* keys for sandbox mode (no real SMS sent) or sk_live_* keys for production delivery.

Headers

Name	Required	Description	Example
`Authorization`	Required	Bearer token with your API key	`Bearer sk_live_...`
`Content-Type`	Required	Must be application/json	`application/json`

Request Body

Name	Type	Required	Description
`to`	`string`	Required	Recipient phone number in E.164 formatExample: `+33612345678`
`body`	`string`	Required	Message content (max 1600 characters)Example: `Hello from Simly!`
`device_id`	`integer`	Optional	Force sending via a specific device IDExample: `123`
`sim_slot`	`integer`	Optional	Sim slot to use (0 or 1)Example: `0`

Code Examples

# Send SMS via Simly API
curl -X POST "https://server-simly.servelink.space/v1/messages" \
  -H "Authorization: Bearer sk_live_..._key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+33612345678",
    "body": "Hello from Simly!",
    "device_id": 123,
    "sim_slot": 0
  }'

Response Example

{
  "id": "msg_abc123xyz",
  "status": "pending",
  "to": "+33612345678",
  "body": "Hello from Simly!",
  "created_at": "2026-01-02T10:30:00Z"
}

Error Responses

Status	Code	Description
400	`invalid_request`	Request validation failed (e.g., invalid phone number format)
400	`missing_parameter`	Required parameter is missing
401	`invalid_api_key`	API key is invalid, revoked, or missing
429	`rate_limit_exceeded`	Too many requests, check Retry-After header
500	`internal_error`	Server error, please retry later

GET/v1/messages/{id}

Get message status

Campaigns

Manage and trigger SMS campaigns

POST/v1/campaigns/{id}/launch

Launch a campaign

Message Statuses

Possible values for the message status field.

Status	Description
`pending`	Message is queued and waiting to be sent
`sending`	Message is being sent via a connected device
`sent`	Message was sent successfully by the device
`delivered`	Message was delivered to the recipient
`failed`	Message delivery failed

Error Handling

All errors follow a consistent JSON format with an error object containing the error details:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'to' field must be a valid E.164 phone number",
    "param": "to"
  }
}

Error Codes

HTTP Status	Error Code	Description
400	`invalid_request`	Request validation failed
400	`missing_parameter`	Required parameter is missing
401	`invalid_api_key`	API key is invalid or revoked
404	`resource_not_found`	Requested resource does not exist
429	`rate_limit_exceeded`	Too many requests, check Retry-After header
500	`internal_error`	Server error, please retry later

Rate Limiting

When rate limited, the response includes a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704189600