SMS API · Reference

SMS API reference

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.

Overview

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.

  • Base URL: https://api.cosmicsms.com
  • Format: XML request and response - header Content-Type: application/xml, encoding UTF-8.
  • Auth: HTTP Basic (see below).
  • Methods: POST to send; GET for status, inbound, cancel and balance.

Authentication

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:

Authorization: Basic R2VvZmZyZXk6QWJDMTIzRGVGNDU2 Content-Type: application/xml
Most HTTP libraries and curl -u "username:password" build this header for you - see the code examples in six languages.

Send SMS

POST/prod/rest/sms/send

Submit a message to one or more recipients (up to 500 per request), with optional scheduling, sender ID, templates and Unicode.

Request parameters

ParameterDescriptionExample
messageThe SMS text. Ignored if template is set. Escape < & > as XML entities.Hello World!
templateOptional. A template id to use instead of message (set up by Cosmic support).1234
paramsOptional. Parameters for dynamic content in a template, e.g. <param1>…</param1>.<param1>1234</param1>
mobileRecipient number(s) inside <mobiles>. International format, no + or leading zeros. UK starts 07 or 447.447700900701
senderSender 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
sendtimeOptional. Schedule delivery (ISO-8601). Omit or set in the past to send now.2026-07-01T13:15Z
multilingualOptional. 0 = GSM-7 (default), 1 = Unicode, 2 = auto-detect Unicode.0, 1 or 2

Request example

<?xml version="1.0" encoding="UTF-8"?> <sendsms> <sender>447700900000</sender> <message>test message</message> <mobiles> <mobile>07700900701</mobile> <mobile>07700900702</mobile> </mobiles> </sendsms>

Response

Returns a batch id (keep it to query delivery status later) and a mobilestatus block per recipient with mobile, statusid and statustext.

<?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>

Submission status values

Status idMeaning
SUCCESSMessage submitted successfully
INVALID_REQUESTInvalid or badly formatted request
INVALID_VALUESMissing or badly formatted value(s)
INVALID_USERInvalid username/password combination
INSUFFICIENT_CREDITInsufficient credit
INVALID_MPNSNo valid mobile numbers supplied
MAX_MPNS_EXCEEDEDToo many mobile numbers (max 500)
INVALID_MESSAGE_LENGTHMessage too long (max 612 characters)
INVALID_DELIVERY_DATEInvalid date/time for scheduled delivery
INVALID_MPNInvalid or badly formatted mobile number
INVALID_SENDERInvalid sender id
INVALID_TEMPLATE / INVALID_PARAMSInvalid template or parameters
SYSTEM_ERRORSystem error - contact support

Code examples

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());

Get delivery status

GET/prod/rest/sms/status/{batch_id}

Returns the delivery status for every recipient in a batch (the batch id comes from the send response).

curl https://api.cosmicsms.com/prod/rest/sms/status/12345678 \ -u "USERNAME:API_PASSWORD"

The response repeats a messagestatus block per recipient: messageid, mobile, statusid, statustext, submittime and deliverytime (ISO-8601; delivery time blank if not known).

Status idMeaning
DELIVEREDMessage successfully delivered
FAILEDMessage failed to deliver
REJECTEDRejected by the network / handset
PENDINGWaiting to be processed
UNKNOWNDelivery status unknown

Get received messages

GET/prod/rest/sms/receive[/{from}[/{to}]]

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.

curl https://api.cosmicsms.com/prod/rest/sms/receive/202601011400 \ -u "USERNAME:API_PASSWORD"

Each message contains messageid, source (sender number), target (your inbound number), text and receivedtime.

Cancel a scheduled message

GET/prod/rest/sms/cancel/{batch_id}

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.

curl https://api.cosmicsms.com/prod/rest/sms/cancel/12345678 \ -u "USERNAME:API_PASSWORD"

Get account balance

GET/prod/rest/account/balance

Returns your current balance and currency - handy for low-credit alerts.

curl https://api.cosmicsms.com/prod/rest/account/balance \ -u "USERNAME:API_PASSWORD" <?xml version="1.0" encoding="UTF-8"?> <getbalance> <balance>65.82</balance> <currency>GBP</currency> </getbalance>

Encoding & characters

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.

PartsGSM-7 charactersUnicode charactersCost
1 SMS160701 × SMS
2 SMS3061342 × SMS
3 SMS4592013 × SMS
4 SMS6122684 × SMS
5 SMS7653355 × SMS
6 SMS9184026 × SMS
In the <message> field, encode XML special characters as entities: < → &lt;, & → &amp;, > → &gt;. Newlines can be embedded directly or as \r\n. Cost = parts × the per-SMS rate for the destination - see pricing.

HTTP status codes

CodeMeaning
200 / 201OK / created - request succeeded
400Bad request - malformed syntax
401Unauthorized - authentication required/incorrect
402Payment required - insufficient funds
404Not found
405Method not allowed
415Unsupported media type
5xxServer error - contact support@cosmicsms.com

Build with an AI assistant

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 &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></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.

Start building today

Create a free account, grab your API credentials and starter credit, and send your first message in minutes. No tie-ins, no setup fee.

Get free test credits → Back to SMS API