The complete Cosmic SMS REST API: connection, authentication, every endpoint with its parameters and responses, status codes and character encoding. Simple XML over HTTPS - works from any language that can make an HTTP request.
All requests go to a single base URL and exchange XML. Create a free account to get credentials and starter credit, then you can send, schedule, track delivery, receive replies and check your balance.
https://api.cosmicsms.comContent-Type: application/xml, encoding UTF-8.POST to send; GET for status, inbound, cancel and balance.Every request uses HTTP Basic authentication. Concatenate your account username and API password with a colon, Base64-encode the result, and send it in the Authorization header.
For username Geoffrey and password AbC123DeF456, the string Geoffrey:AbC123DeF456 Base64-encodes to R2VvZmZyZXk6QWJDMTIzRGVGNDU2:
curl -u "username:password" build this header for you - see the code examples in six languages.Submit a message to one or more recipients (up to 500 per request), with optional scheduling, sender ID, templates and Unicode.
| Parameter | Description | Example |
|---|---|---|
| message | The SMS text. Ignored if template is set. Escape < & > as XML entities. | Hello World! |
| template | Optional. A template id to use instead of message (set up by Cosmic support). | 1234 |
| params | Optional. Parameters for dynamic content in a template, e.g. <param1>…</param1>. | <param1>1234</param1> |
| mobile | Recipient number(s) inside <mobiles>. International format, no + or leading zeros. UK starts 07 or 447. | 447700900701 |
| sender | Sender shown on the handset. Alphanumeric max 11 (a-z A-Z 0-9 _-, no spaces) or numeric max 15. For inbound replies, use a number. | CosmicSMS |
| sendtime | Optional. Schedule delivery (ISO-8601). Omit or set in the past to send now. | 2026-07-01T13:15Z |
| multilingual | Optional. 0 = GSM-7 (default), 1 = Unicode, 2 = auto-detect Unicode. | 0, 1 or 2 |
Returns a batch id (keep it to query delivery status later) and a mobilestatus block per recipient with mobile, statusid and statustext.
| Status id | Meaning |
|---|---|
| SUCCESS | Message submitted successfully |
| INVALID_REQUEST | Invalid or badly formatted request |
| INVALID_VALUES | Missing or badly formatted value(s) |
| INVALID_USER | Invalid username/password combination |
| INSUFFICIENT_CREDIT | Insufficient credit |
| INVALID_MPNS | No valid mobile numbers supplied |
| MAX_MPNS_EXCEEDED | Too many mobile numbers (max 500) |
| INVALID_MESSAGE_LENGTH | Message too long (max 612 characters) |
| INVALID_DELIVERY_DATE | Invalid date/time for scheduled delivery |
| INVALID_MPN | Invalid or badly formatted mobile number |
| INVALID_SENDER | Invalid sender id |
| INVALID_TEMPLATE / INVALID_PARAMS | Invalid template or parameters |
| SYSTEM_ERROR | System error - contact support |
Sending an SMS in six common languages. Replace USERNAME and API_PASSWORD with your credentials; the same Basic-auth pattern applies to every endpoint.
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>'
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)
const xml = `<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
<sender>CosmicSMS</sender>
<message>Hello from Cosmic SMS!</message>
<mobiles>
<mobile>447700900701</mobile>
</mobiles>
</sendsms>`;
const auth = Buffer.from("USERNAME:API_PASSWORD").toString("base64");
const res = await fetch("https://api.cosmicsms.com/prod/rest/sms/send", {
method: "POST",
headers: {
"Content-Type": "application/xml",
Authorization: `Basic ${auth}`,
},
body: xml,
});
console.log(res.status, await res.text());
<?php
$xml = '<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
<sender>CosmicSMS</sender>
<message>Hello from Cosmic SMS!</message>
<mobiles>
<mobile>447700900701</mobile>
</mobiles>
</sendsms>';
$ch = curl_init("https://api.cosmicsms.com/prod/rest/sms/send");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $xml,
CURLOPT_HTTPHEADER => ["Content-Type: application/xml"],
CURLOPT_USERPWD => "USERNAME:API_PASSWORD",
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL . $response;
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
var xml = @"<?xml version=""1.0"" encoding=""UTF-8""?>
<sendsms>
<sender>CosmicSMS</sender>
<message>Hello from Cosmic SMS!</message>
<mobiles>
<mobile>447700900701</mobile>
</mobiles>
</sendsms>";
using var client = new HttpClient();
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes("USERNAME:API_PASSWORD"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", auth);
var content = new StringContent(xml, Encoding.UTF8, "application/xml");
var res = await client.PostAsync("https://api.cosmicsms.com/prod/rest/sms/send", content);
Console.WriteLine((int)res.StatusCode);
Console.WriteLine(await res.Content.ReadAsStringAsync());
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
String xml = """
<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
<sender>CosmicSMS</sender>
<message>Hello from Cosmic SMS!</message>
<mobiles>
<mobile>447700900701</mobile>
</mobiles>
</sendsms>""";
String auth = Base64.getEncoder()
.encodeToString("USERNAME:API_PASSWORD".getBytes());
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.cosmicsms.com/prod/rest/sms/send"))
.header("Content-Type", "application/xml")
.header("Authorization", "Basic " + auth)
.POST(HttpRequest.BodyPublishers.ofString(xml))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
Returns the delivery status for every recipient in a batch (the batch id comes from the send response).
The response repeats a messagestatus block per recipient: messageid, mobile, statusid, statustext, submittime and deliverytime (ISO-8601; delivery time blank if not known).
| Status id | Meaning |
|---|---|
| DELIVERED | Message successfully delivered |
| FAILED | Message failed to deliver |
| REJECTED | Rejected by the network / handset |
| PENDING | Waiting to be processed |
| UNKNOWN | Delivery status unknown |
Returns inbound messages sent to your virtual number or short code, newest first (max 1,000 per call). No dates = today; add a start (and optional end) datetime in yyyyMMddHHmm format for a range.
Each message contains messageid, source (sender number), target (your inbound number), text and receivedtime.
Cancels delivery for a scheduled batch that hasn't sent yet. Returns a getrefund block with the refunded amount and currency; an invalid or already-sent batch returns INVALID_PARAMS.
Returns your current balance and currency - handy for low-credit alerts.
GSM-7 is the default and suits English and most West-European languages. Set multilingual=1 for Unicode (any language, symbols, emoji). Longer messages are split into parts and reassembled on the handset; each part is charged as one SMS.
| Parts | GSM-7 characters | Unicode characters | Cost |
|---|---|---|---|
| 1 SMS | 160 | 70 | 1 × SMS |
| 2 SMS | 306 | 134 | 2 × SMS |
| 3 SMS | 459 | 201 | 3 × SMS |
| 4 SMS | 612 | 268 | 4 × SMS |
| 5 SMS | 765 | 335 | 5 × SMS |
| 6 SMS | 918 | 402 | 6 × SMS |
<message> field, encode XML special characters as entities: < → <, & → &, > → >. Newlines can be embedded directly or as \r\n. Cost = parts × the per-SMS rate for the destination - see pricing.| Code | Meaning |
|---|---|
| 200 / 201 | OK / created - request succeeded |
| 400 | Bad request - malformed syntax |
| 401 | Unauthorized - authentication required/incorrect |
| 402 | Payment required - insufficient funds |
| 404 | Not found |
| 405 | Method not allowed |
| 415 | Unsupported media type |
| 5xx | Server error - contact support@cosmicsms.com |
Paste this structured context into ChatGPT or Claude and it has everything needed to generate correct integration code in any language.
COSMIC SMS API - context for code generation
Base URL: https://api.cosmicsms.com
Auth: HTTP Basic (account username + API password), Base64 in the Authorization header.
Format: XML request and response. Header Content-Type: application/xml; encoding UTF-8.
SEND SMS - POST /prod/rest/sms/send
<?xml version="1.0" encoding="UTF-8"?>
<sendsms>
<sender>CosmicSMS</sender> <!-- alphanumeric max 11, or numeric max 15 -->
<message>Hello World!</message> <!-- escape < & > as < & > -->
<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></mobiles> <!-- intl format, no + or 0; max 500 -->
</sendsms>
Response: <sendsms><batch>ID</batch><mobilestatus><mobile/><statusid>SUCCESS</statusid><statustext/></mobilestatus></sendsms>
OTHER ENDPOINTS (HTTP GET, same Basic auth)
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 status ids: 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.
DELIVERY status ids: DELIVERED, FAILED, REJECTED, UNKNOWN, PENDING.
HTTP codes: 200/201 ok, 400 bad request, 401 unauthorised, 402 insufficient funds, 404, 405, 415, 5xx.
ENCODING: GSM-7 = 160 chars single / 153 per concatenated part.
Unicode (multilingual=1) = 70 single / 67 per part. Max 918 GSM-7 (6 parts).
Cost = number of parts x the per-SMS rate for the destination.
Prefer a file? Download the Markdown spec or the PDF specification.
Create a free account, grab your API credentials and starter credit, and send your first message in minutes. No tie-ins, no setup fee.