API Documentation — Celer Cloud SMS API Reference

Authentication

All requests require API key authentication via the X-API-Key header.

curl -X POST https://api.celerd.com/v1/messages \ -H "X-API-Key: sk_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{"to":"+1234567890","from":"CelerCloud","content":"Hello"}'

Quick Start

1

Get API Keys

Sign up and find your keys in Dashboard → Settings

2

Make a Request

Use the endpoint with your API key header

3

Handle Response

Parse JSON response and handle status codes

POST /messages

Send SMS

Create and send a new message to any destination worldwide.

Request Body

Field	Type	Required	Description
`to`	string	Required	Recipient phone number (E.164 format, e.g. +1234567890)
`from`	string	Required	Sender ID (alphanumeric or numeric, 1-11 characters)
`content`	string	Required	Message body (max 160 GSM-7 / 70 Unicode chars)

Example Request

curl -X POST https://api.celerd.com/v1/messages \ -H "X-API-Key: sk_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "to": "+1234567890", "from": "CelerCloud", "content": "Your verification code is: 847291" }'

Response (201 Created)

{
  "id": "msg_abc123",
  "to": "+1234567890",
  "from": "CelerCloud",
  "content": "Your verification code is: 847291",
  "status": "queued",
  "segments": 1,
  "cost": 0.015,
  "currency": "USD",
  "created_at": "2026-05-20T06:12:00Z"
}
      
      

Code Examples

Python

# pip install requests

import requests

response = requests.post(
    "https://api.celerd.com/v1/messages",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "to": "+1234567890",
        "from": "CelerCloud",
        "content": "Your verification code is: 847291"
    }
)

data = response.json()
print(data["id"])      # msg_abc123
print(data["status"])  # queued

Node.js

// npm install axios

const axios = require('axios');

const res = await axios.post(
  'https://api.celerd.com/v1/messages',
  { to: '+1234567890', from: 'CelerCloud', content: 'Your verification code is: 847291' },
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);

console.log(res.data.id);      // msg_abc123
console.log(res.data.status);  // queued

Java

// pom.xml:
//   com.squareup.okhttp3:okhttp:4.12.0

import okhttp3.*;
import java.io.IOException;

public class SendSMS {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        String json = "{\"to\":\"+1234567890\",\"from\":\"CelerCloud\",\n \"content\":\"Your code is: 847291\"}";

        Request request = new Request.Builder()
            .url("https://api.celerd.com/v1/messages")
            .header("X-API-Key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .post(RequestBody.create(json, MediaType.parse("application/json")))
            .build();

        try (Response res = client.newCall(request).execute()) {
            System.out.println(res.body().string());
        }
    }
}

PHP

<?php
// composer require guzzlehttp/guzzle

require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$response = $client->post('https://api.celerd.com/v1/messages', [
    'headers' => [
        'X-API-Key' => 'YOUR_API_KEY',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'to' => '+1234567890',
        'from' => 'CelerCloud',
        'content' => 'Your code is: 847291',
    ],
]);

$data = json_decode($response->getBody(), true);
echo $data['id'];      // msg_abc123
echo $data['status'];  // queued

C#

// dotnet add package Newtonsoft.Json

using System.Net.Http;
using System.Text;
using Newtonsoft.Json;

class Program {
    static async Task Main() {
        var client = new HttpClient();
        var payload = new {
            to = "+1234567890",
            from = "CelerCloud",
            content = "Your code is: 847291"
        };

        var request = new HttpRequestMessage(HttpMethod.Post,
            "https://api.celerd.com/v1/messages");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        request.Content = new StringContent(
            JsonConvert.SerializeObject(payload),
            Encoding.UTF8, "application/json");

        var res = await client.SendAsync(request);
        Console.WriteLine(await res.Content.ReadAsStringAsync());
    }
}

Go

package main

import (
    "bytes"
    "fmt"
    "net/http"
)

func main() {
    body := []byte(`{"to":"+1234567890","from":"CelerCloud","content":"Your code is: 847291"}`)
    req, _ := http.NewRequest("POST", "https://api.celerd.com/v1/messages", bytes.NewReader(body))
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var buf bytes.Buffer
    buf.ReadFrom(resp.Body)
    fmt.Println(buf.String())
    // {"id":"msg_abc123","status":"queued",...}
}

GET /messages

List Messages

Paginated list of sent messages with filtering options.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 50, max: 200)
`status`	string	Filter: queued / delivered / failed / pending
`date_from`	string	Start date (ISO 8601)
`date_to`	string	End date (ISO 8601)

Code Examples

Python

import requests

response = requests.get(
    "https://api.celerd.com/v1/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"page": 1, "limit": 30, "status": "delivered"}
)

data = response.json()
print(len(data["items"]))  # 30

Node.js

const axios = require('axios');

const { data } = await axios.get(
  'https://api.celerd.com/v1/messages',
  {
    headers: { 'X-API-Key': 'YOUR_API_KEY' },
    params: { page: 1, limit: 30, status: 'delivered' }
  }
);

console.log(data.items.length);  // 30

Java

import java.net.http.*;
import java.net.URI;

public class ListMessages {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.celerd.com/v1/messages?page=1&limit=30&status=delivered"))
            .header("X-API-Key", "YOUR_API_KEY")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

$client = new \GuzzleHttp\Client();
$response = $client->get('https://api.celerd.com/v1/messages', [
    'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
    'query'   => ['page' => 1, 'limit' => 30, 'status' => 'delivered'],
]);

$data = json_decode($response->getBody(), true);
echo count($data['items']);  // 30

C#

using System.Net.Http;
using System.Threading.Tasks;

class Program {
    static async Task Main() {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Get,
            "https://api.celerd.com/v1/messages?page=1&limit=30&status=delivered");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");

        var response = await client.SendAsync(request);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Go

import (
    "fmt"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.celerd.com/v1/messages?page=1&limit=30&status=delivered", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var buf bytes.Buffer
    buf.ReadFrom(resp.Body)
    fmt.Println(buf.String())
}

PHP

<?php

$client = new \GuzzleHttp\Client();
$response = $client->get('https://api.celerd.com/v1/messages', [
    'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
    'query'   => ['page' => 1, 'limit' => 30, 'status' => 'delivered'],
]);

$data = json_decode($response->getBody(), true);
echo count($data['items']);  // 30

GET /account/balance

Get Balance

Check current account balance and usage statistics.

Response (200 OK)

{
  "status": "ok",
  "balance": 250.75,
  "currency": "USD",
  "credit_limit": 1000.00
}
      
      

Code Examples

Python

import requests

response = requests.get(
    "https://api.celerd.com/v1/account/balance",
    headers={"X-API-Key": "YOUR_API_KEY"}
)

data = response.json()
print(data["balance"])  # 250.75

Node.js

const axios = require('axios');

const { data } = await axios.get(
  'https://api.celerd.com/v1/account/balance',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);

console.log(data.balance);  // 250.75

Java

import java.net.http.*;
import java.net.URI;

public class GetBalance {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.celerd.com/v1/account/balance"))
            .header("X-API-Key", "YOUR_API_KEY")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
        // {"status":"ok","balance":250.75,...}
    }
}

PHP

<?php

$client = new \GuzzleHttp\Client();
$response = $client->get('https://api.celerd.com/v1/account/balance', [
    'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
]);

$data = json_decode($response->getBody(), true);
echo $data['balance'];  // 250.75

C#

using System.Net.Http;
using System.Threading.Tasks;

class Program {
    static async Task Main() {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Get,
            "https://api.celerd.com/v1/account/balance");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");

        var response = await client.SendAsync(request);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
        // {"status":"ok","balance":250.75,...}
    }
}

Go

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.celerd.com/v1/account/balance", nil)
    req.Header.Set("X-API-Key", "YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
    // {"status":"ok","balance":250.75,...}
}

PHP

<?php

$client = new \GuzzleHttp\Client();
$response = $client->get('https://api.celerd.com/v1/account/balance', [
    'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
]);

$data = json_decode($response->getBody(), true);
echo $data['balance'];  // 250.75

POST /account/keys

Manage API Keys

Create, list, or revoke API keys for your account.

POST /webhooks

Configure Webhooks

Set up webhook endpoints to receive delivery status callbacks.

Push Payload (data structure sent to your endpoint)

{
  "event": "message.delivered",
  "data": {
    "message_id": "msg_abc123",
    "to": "+1234567890",
    "from": "CelerCloud",
    "status": "delivered",
    "cost": 0.015,
    "currency": "USD",
    "delivered_at": "2026-05-20T06:12:08Z"
  }
}
      
      

Error Codes

API Errors

101AccessKey error.

102AccessKey is disabled.

104The scheduled time cannot be less than 10 minutes or more than 15 days.

107No balance.

108Incorrect phone number.

113Incorrect date.

115AccessKey error.

122AccessKey error.

123The length of content is too long.

136The account has been frozen or deactivated and cannot be operated. If you have any questions, please contact the administrator.

137IP access limited.

139This account has not been verified yet, please complete the verification first.

144Incorrect price.

145Blacklist failed.

146SenderID error.

147Content error.

500SERVER ERROR

SMPP Protocol Errors

0STATUS_OKSuccessNormal request processing.

1STATUS_INVMSGLENInvalid message length.Long SMS segment count exceeds limit.

8STATUS_SYSERRSystem error.Application/client status error or internal server error.

10STATUS_INVSRCADRInvalid source address.Source address format or content is invalid.

11STATUS_INVDSTADRInvalid destination address.Phone number is empty, invalid format, or exceeds 20 digits.

13STATUS_BINDFAILBind failed.system_id / password authentication failed.

88STATUS_THROTTLEDThrottled.Request rate limit exceeded.

SMPP Delivery Receipt (DLR) Errors

001REJECTDInsufficient balance.

002REJECTDInvalid phone number.

003REJECTDCountry not quoted.

004REJECTDBlacklisted.

005REJECTDNot in sender whitelist.

006REJECTDContent does not meet whitelist requirements.

007REJECTDRoute and template did not match any channel.

008REJECTDChannel template management — rejected.

009REJECTDPlatform risk interception.

010REJECTDCustomer number segment blocked.

011REJECTDChannel number segment blocked.

API Reference

Base URL

Authentication

Quick Start

Send SMS

Request Body

Example Request

Response (201 Created)

Code Examples

List Messages

Query Parameters

Code Examples

Get Balance

Response (200 OK)

Code Examples

Manage API Keys

Configure Webhooks

Push Payload (data structure sent to your endpoint)

Error Codes

API Errors

SMPP Protocol Errors

SMPP Delivery Receipt (DLR) Errors