SMS API for New CaledoniaAn order ships, a text follows. Your code handles the rest.
Parcels, appointments, alerts: your software sends the SMS under your name, and the delivery receipt comes back to your code, signed.
Updated on · SMS PRO team
New Caledonia's bulk SMS pioneers since 2016. Public OpenAPI 3.1 specification; you create your keys once your account is open.
Ten years of New Caledonian SMS, now inside your code.
Since 2016, we have been sending SMS for organisations across New Caledonia. The SMS PRO API puts that experience behind a single HTTP call, with a team in Nouméa you can actually pick up the phone to.
One call, one SMS
A sender, a message, recipients. In cURL, PHP or JavaScript.
The receipt comes to you
A signed webhook tells your software when the network confirms delivery.
Never sent twice
With an idempotency key, a retried call does not send the SMS again.
Data in New Caledonia
Sends, receipts and logs stored in the
Stratos sovereign cloud in New Caledonia.
Your code calls. The phone buzzes. The receipt comes back.
Watch an order go out. Then replay the exact same call, as you would after a timeout: the phone does not buzz a second time.
- Waiting for an order
No message yet
- Your code calls
- SMS PRO accepts
- The phone buzzes
- The receipt comes back
Three fields, and your SMS is on its way.
A sender, a message, recipients. Invalid or opted-out numbers are set aside and counted in the response, without failing the call.
Numbers in international format (+687560001) or as 6 local digits. An optional field schedules the send, with its time offset: UTC+11 for Nouméa. Everything else is in the OpenAPI specification.
# SMSPRO_API: the base URL given in the OpenAPI specification
# SMSPRO_KEY: a key created in your client area
curl -X POST "$SMSPRO_API/messages" \
-H "Authorization: Bearer $SMSPRO_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{
"sender": "STORE EX",
"message": "Example Store: your order 1042 is on its way. Track it here: brf.nc/Ex7k",
"recipients": ["+687560001"]
}'<?php
// SMSPRO_API: the base URL given in the OpenAPI specification
$ch = curl_init(getenv('SMSPRO_API') . '/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SMSPRO_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order-' . $order['id'],
],
CURLOPT_POSTFIELDS => json_encode([
'sender' => 'STORE EX',
'message' => "Example Store: your order {$order['id']} is on its way. Track it here: brf.nc/Ex7k",
'recipients' => [$customer['mobile']],
]),
]);
$send = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 201) {
// Standard error format: branch on 'code', never on 'detail'
error_log("Send rejected: {$send['code']}");
}// Node.js 18 or later. SMSPRO_API: the base URL given in the OpenAPI specification
const response = await fetch(`${process.env.SMSPRO_API}/messages`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SMSPRO_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': `order-${order.id}`,
},
body: JSON.stringify({
sender: 'STORE EX',
message: `Example Store: your order ${order.id} is on its way. Track it here: brf.nc/Ex7k`,
recipients: [customer.mobile],
}),
});
const send = await response.json();
if (response.status !== 201) console.error('Send rejected:', send.code);Out on the veranda, a phone buzzes. Your name is on the screen.
Your customer reads the message under your registered sender ID. Your code, meanwhile, knows how many recipients went out, how many were set aside, and how many SMS parts the message takes.
HTTP/1.1 201 Created
{
"id": "1364012",
"status": "accepted",
"sender": "STORE EX",
"encoding": "GSM-7",
"parts_per_message": 1,
"accepted_recipients": 1,
"stopped_recipients": 0,
"invalid_recipients": [],
"created_at": "2026-11-11T08:30:00+11:00"
}"accepted" means accepted and queued, not yet on the phone.
72 characters · 1 SMS
Stop polling the API. It lets you know.
For SMS sent to a New Caledonian mobile, the local operator returns a delivery receipt. SMS PRO matches it to the message and notifies your software with a timestamped notification, signed with HMAC-SHA256.
SMS delivered or failed, send completed, survey answered: you choose your events. No receipt, no "delivered": the status stays "sent". The same delivery statuses as in the app: delivered, not delivered, not confirmed.
curl -X POST "$SMSPRO_API/webhooks" \
-H "Authorization: Bearer $SMSPRO_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Order tracking",
"url": "https://your-domain.example/sms/receipt",
"events": ["sms.delivered", "sms.failed"]
}'<?php
// $signature: the value of the signature header (its name is in the documentation)
// $secret: the secret shown once, when the webhook is created
[$t, $v1] = sscanf($signature, 't=%d,v1=%s');
$expected = hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $v1) || abs(time() - $t) > 300) {
http_response_code(403); // wrong signature, or message too old: replay rejected
exit;
}
http_response_code(200);curl "$SMSPRO_API/messages/1364012/deliveries?phone=%2B687560001" \
-H "Authorization: Bearer $SMSPRO_KEY"
{
"deliveries": [
{
"recipient": "+687560001",
"state": "delivered",
"parts": 1,
"sent_at": "2026-11-11T08:30:01+11:00",
"delivered_at": "2026-11-11T08:31:12+11:00",
"error": null
}
]
}Timed out? Retry without a second thought.
With an idempotency key, a retried call never sends twice: the API returns the original response. One key per business operation, the same key for every retry.
| Your software sends | The API replies |
|---|---|
| A key it has never seen | The send is processed and the response stored. |
| Same key, same content | The original response comes back, flagged as a replay. Nothing runs twice. |
| Same key, different content | Refused: that's an integration error, and the API says so. |
| Same key, first call still running | Hold on: the API tells you when to try again. |
Equipping several organisations? Each one keeps its own name.
A group workspace oversees several organisations from a single login. Each keeps its own contract, sender IDs, STOP list and history.
Every name is registered before its first send: the API refuses a sender that is not assigned to your account. Does your software publish a calendar instead? See how to connect a calendar or business software.
Business software vendors
The online store announces the parcel
The clinic's software sends the reminder
The school office alerts parentsIT departments too: an alert goes off, an on-call shift begins, and the right person gets an SMS.
One key per integration. One STOP list for everyone.
Each key has a name, its own permissions and, if you wish, the IP addresses of your servers. It is shown only once: we only keep a hash of it.
An opted-out number is set aside whether the app or your code targets it, thanks to the organisation's opt-out link. How your secrets are protected: security and storage in New Caledonia.
Enough to wire up a whole application, not just a button.
Sends
Right away or on a date you choose; track, list and cancel anything still in the queue.
Recipients
The status of every recipient, or of just one, with the receipt time and a readable reason for any failure.
Contact groups
Create and extend them, and name your columns to turn them into message fields.
STOP list
Read it, add to it, replace your imports, without touching anyone who opted out themselves.
Attachments
Upload a file and get a short doc.nc link, built to fit inside an SMS.
Webhooks
Subscribe, review deliveries and their failures, replay a notification.
JSON, RFC 3339 timestamps, RFC 9457 errors with a stable code, cursor-based pagination, advertised rate limits, and a request ID to quote to our team.
SMS to New Caledonian mobiles go out directly through the local operator. To French Polynesia, Vanuatu, Australia, New Zealand and mainland France, they travel over international routing; other destinations on request. Your data is stored in New Caledonia, in the
Stratos sovereign cloud.
Your questions, answered.
Where is the SMS API documentation?
The OpenAPI 3.1 specification is public: load it into your API testing tool or generate a client in your language. The readable documentation, with examples, opens in your client area.
How do I get an API key?
Once our team has opened your account, you create your keys from your client area. Each key has a name and its own permissions, and is shown only once: keep it in an environment variable or a secrets vault.
Can a key be restricted to our servers?
Yes. Each key can be locked to your servers' IP addresses: a call from anywhere else is refused, even with the right key. Create one key per integration, with only the permissions it needs.
How do I know an SMS has been delivered?
Subscribe to webhooks and you are notified as soon as the receipt arrives. You can also ask for the status of one specific recipient. For SMS sent to a New Caledonian mobile, the operator returns a delivery receipt; without one, the status stays "sent", never "delivered".
What happens if a call is retried?
With an idempotency key, a retried call never sends twice: the API returns the original response without running anything again. The same key with different content is refused, so the integration error does not go unnoticed.
Can we send under each of our clients' names?
Yes, as long as each name is registered before its first send. Send us the list: we register each name and check it with a real send. Otherwise, keep your own sender ID and mention your client in the message text.
Related pages
Connected calendars and software
Google Calendar, Outlook, clinic and optician software: the other ways to plug in SMS PRO.
Tracking every SMS
Delivered, not delivered, not confirmed: what each status means.
STOP opt-out
The opt-out link, its confirmation code, and how it applies across every account.
Security and data
Storage in New Caledonia, encrypted secrets, two-factor authentication.
Somewhere, a customer is waiting to hear.
Tell us what your software does and when it needs to send. An adviser in Nouméa calls you back, opens your account and registers your sender ID: your first key comes with ten years of New Caledonian SMS behind it.
50 free SMS to try, no commitment: contact@smspro.nc