# Cosmic SMS - REST API (context for developers & AI assistants)

A compact, machine-readable summary of the Cosmic SMS REST API (spec v4.3). Paste this into an AI assistant to generate integration code, or use it as a quick reference. Full PDF specification: https://www.cosmicsms.com/files/Cosmic-SMS-REST-API.pdf

## Basics

- **Base URL:** `https://api.cosmicsms.com`
- **Auth:** HTTP Basic - `username:API_PASSWORD`, Base64-encoded in the `Authorization: Basic …` header.
- **Format:** XML request and response. Header `Content-Type: application/xml`, encoding UTF-8.
- **HTTP status codes:** 200/201 ok · 400 bad request · 401 unauthorised · 402 insufficient funds · 404 not found · 405 method not allowed · 415 unsupported media type · 5xx server error.

## Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/prod/rest/sms/send` | Send to 1-500 recipients |
| GET | `/prod/rest/sms/status/{batch_id}` | Delivery status for a batch |
| GET | `/prod/rest/sms/receive[/{from}[/{to}]]` | Inbound messages (dates `yyyyMMddHHmm`) |
| GET | `/prod/rest/sms/cancel/{batch_id}` | Cancel a scheduled batch |
| GET | `/prod/rest/account/balance` | Current credit balance |

## Send SMS - request

`POST /prod/rest/sms/send`

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
  <sender>CosmicSMS</sender>              <!-- alphanumeric max 11, or numeric max 15 -->
  <message>Hello World!</message>         <!-- escape < & > as &lt; &amp; &gt; -->
  <sendtime>2026-07-01T13:15Z</sendtime>  <!-- optional ISO-8601; omit = send now -->
  <multilingual>2</multilingual>          <!-- 0=GSM-7 default, 1=Unicode, 2=auto -->
  <mobiles>
    <mobile>447700900701</mobile>         <!-- international format, no + or leading 0; max 500 -->
  </mobiles>
</sendsms>
```

Optional: `<template>ID</template>` with `<params><param1>…</param1></params>` instead of `<message>` (templates set up by Cosmic support).

## Send SMS - response

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
  <batch>20154010</batch>
  <mobilestatus>
    <mobile>447700900701</mobile>
    <statusid>SUCCESS</statusid>
    <statustext>Success: Message submitted successfully</statustext>
  </mobilestatus>
</sendsms>
```

Keep the `<batch>` id to query delivery status later.

## Status values

- **Submission (`statusid` on send):** SUCCESS, INVALID_REQUEST, INVALID_VALUES, INVALID_USER, INSUFFICIENT_CREDIT, SYSTEM_ERROR, INVALID_MPNS, MAX_MPNS_EXCEEDED, INVALID_MESSAGE_LENGTH, INVALID_DELIVERY_DATE, INVALID_MPN, INVALID_SENDER, INVALID_RECEIPT_URL, INVALID_TEMPLATE, INVALID_PARAMS.
- **Delivery (`statusid` on status):** DELIVERED, FAILED, REJECTED, UNKNOWN, PENDING.

## Encoding & segments

- **GSM-7** (default): 160 chars single, 153 per concatenated part.
- **Unicode** (`multilingual=1`): 70 chars single, 67 per part.
- Max 918 GSM-7 characters (6 parts). Each part is charged as one SMS; cost = parts × destination per-SMS rate.
- Escape `<` `&` `>` inside `<message>` as `&lt;` `&amp;` `&gt;`.

## Example - send (cURL)

```bash
curl https://api.cosmicsms.com/prod/rest/sms/send \
  -u "USERNAME:API_PASSWORD" \
  -H "Content-Type: application/xml" \
  --data-binary '<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
  <sender>CosmicSMS</sender>
  <message>Hello from Cosmic SMS!</message>
  <mobiles><mobile>447700900701</mobile></mobiles>
</sendsms>'
```

## Example - send (Python)

```python
import requests

xml = """<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
  <sender>CosmicSMS</sender>
  <message>Hello from Cosmic SMS!</message>
  <mobiles><mobile>447700900701</mobile></mobiles>
</sendsms>"""

resp = requests.post(
    "https://api.cosmicsms.com/prod/rest/sms/send",
    data=xml.encode("utf-8"),
    headers={"Content-Type": "application/xml"},
    auth=("USERNAME", "API_PASSWORD"),
)
print(resp.status_code, resp.text)
```

---
_Cosmic SMS · Cosmic Apps Ltd · support@cosmicsms.com · +44 (0) 20 7183 9065. Rates and details illustrative for the website rebuild; the PDF specification is canonical._
