Dingo Mail v5 API Reference

5c SMS & Dingo Mail API

One API for business messaging across two channels: SMS through 5c SMS and email through Dingo Mail. Send and track SMS, hold two-way conversations, read inbound messages, and manage opt-outs, sender IDs and virtual numbers. Send transactional and bulk email from your own verified sending domains, with delivery status on every message. Endpoints are secure, JSON over HTTPS, and grouped in the sidebar by area.

Getting started

Step 1: Generate your API key.

  1. Go to https://www.5centsms.com.au/dashboard/api
  2. In API Key Management, set a Key Alias to identify the key.
  3. Click Create New API Key.
  4. Copy the generated Key ID and Key Secret.

The same key authenticates both the 5c SMS endpoints and the Dingo Mail email endpoints.

Important: Store your credentials securely. The Key Secret is shown only once and cannot be retrieved again.

Step 2: Send your first SMS.

curl -X POST https://www.5centsms.com.au/api/v5/sms \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "Paste Key ID here",
    "key-secret": "Paste Key Secret here",
    "sender": "0404123123",
    "to": "Paste recipient number here",
    "message": "Hello World"
  }'

Step 3: Send your first email.

curl -X POST https://api.dingomail.com.au/api/v5/email \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "Paste Key ID here",
    "key-secret": "Paste Key Secret here",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Hello",
    "Text": "Hello World",
    "Recipient": "Paste recipient email here"
  }'

Email sends from a verified sending domain. Register one with Create Domain (under Email Domains) or in the dashboard, then use any address at that domain as the SenderEmail.

Authentication

Every request authenticates with your key-id and key-secret supplied in the JSON request body (set them once as the key_id / key_secret collection variables and they apply to every request here). All requests must use HTTPS — a plain HTTP request is rejected with 400 HTTPS Required.

Responses & errors

Every response is JSON and carries an error field. The HTTP status follows from it:

  • HTTP 200 — success; error is an empty string ("").
  • HTTP 400 — the request failed; the reason is in error.
  • HTTP 401 — authentication failed (see the table below).
  • HTTP 503 — the API is in maintenance; retry shortly.

An unsupported method/path combination returns Unsupported method. Please see our API Docs.

Authentication errors (HTTP 401):

Error Cause
Failed (Invalid Key ID) The key-id is missing or not recognised.
Failed (Invalid Key Secret) The key-secret does not match the key.
Failed (Invalid API ID or Key) The key id/secret pair is invalid.
Failed (Invalid Username or API Key) Legacy credential pair is invalid.

API hosts

Two base URLs back this collection, preset as variables:

  • https://www.5centsms.com.au/api/v5 (5c SMS): SMS, Conversations, Account, Logins, Sender IDs, Virtual Numbers.
  • https://api.dingomail.com.au/api/v5 (Dingo Mail): Email and Email Domains.

Pagination

List endpoints return results newest-first, one page at a time. To fetch the next page, pass the last item's id as the after query parameter. after is a 24-character hex cursor (a MongoDB ObjectId), not an offset or page number.

Each list response includes next_page — a ready-to-use relative path already containing the after value for the following page — and count (items on the current page). Follow next_page until it is absent or empty.

next_page is a root-relative path beginning with / (for example /api/v5/sms?after=...). Resolve it against the API host (scheme + host of the base URL), not against the current request path, then re-send with the same credentials.

Cursor-paginated endpoints (Conversations) return next_cursor instead: pass it back as the before parameter, and stop when it is null.

Page sizes are fixed per endpoint:

Endpoint Page size
List Emails 20 (override with limit, 1–100)
List Inbound Messages 50
List Opt-outs 1000

A malformed after returns HTTP 400 — Failed (Invalid Page) on the SMS / Inbox / Opt-out endpoints, Invalid after parameter on List Emails (which also rejects a bad limit with Invalid limit parameter). Logins, Sender IDs, Virtual Numbers, and Email Domains return full unpaginated lists.

Message status codes

The status field on a message maps to a human-readable status_text. For the full list of status codes and their meanings, see Message Status List.

Data retention

Message data is retained for 365 days from the date of processing, after which it is permanently purged. Contact support if you require a different retention timeframe.

Using Postman

Download this collection and import it into Postman (Import → File, or paste the raw link). Set the key_id and key_secret collection variables once under the collection's Variables tab, then open any request and click Send. Each request's Documentation pane (the right-hand panel) shows its parameters, response fields, and errors.

Base URLs
SMS:   https://www.5centsms.com.au/api/v5
Email: https://api.dingomail.com.au/api/v5
Authentication (JSON body, every request)
{
    "key-id": "your-key-id",
    "key-secret": "your-key-secret"
}

POST Send SMS

POST https://www.5centsms.com.au/api/v5/sms

Include key-id and key-secret in the JSON body of every request.

Send a single SMS to one or more recipients.

Request body parameters

Field Type Required Description
sender string Yes Sender ID. Max 13 characters; max 11 if alphanumeric ([0-9a-zA-Z] only).
to string Yes Recipient number(s), comma-separated. International or 04 format.
message string Yes Message content. Hex-encoded UTF-16 when unicode is true.
test boolean No Simulate the send — no SMS delivered, no credits charged. Default false.
unicode boolean No Send as UTF-16; message must be hex-encoded. Must be enabled on your account. Deprecated for new accounts; use a Unified Virtual Number for rich text messaging. Default false.
schedule integer No UNIX epoch seconds for future delivery, max 356 days ahead.

Response fields

Field Type Description
error string Empty on success.
messages array One entry per recipient.
messages[].destination string Recipient number.
messages[].id string Message id.
messages[].status integer Status code (see Introduction).
messages[].status_text string Human-readable status.
messages[].credits number Credits charged.
messages[].schedule integer Scheduled epoch — only when the message is scheduled (status 1005).

Errors

Error HTTP Cause
Failed (Invalid Sender ID) 400 sender missing, >13 chars, or alphanumeric >11 chars / invalid characters.
Failed (Invalid Destination) 400 to missing.
Failed (Invalid Message) 400 message missing.

Notes

  • With unicode, emoji and non-GSM text are supported; e.g. Testing🎉 hex-encodes to 00540065007300740069006E0067D83CDF89.
  • Use test: true to verify integration without sending or charging.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/sms \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/sms"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
});

const req = https.request("https://www.5centsms.com.au/api/v5/sms", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/sms");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/sms"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/sms");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""sender"": ""0404123123"",
    ""to"": ""0412333555"",
    ""message"": ""Hello World"",
    ""test"": false,
    ""unicode"": false,
    ""schedule"": 0
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/sms", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/sms")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "messages": [
    {
      "destination": "0412333555",
      "id": "683554c596937cc4b90f5cf7",
      "status": 1011,
      "status_text": "Sending...",
      "credits": 1
    }
  ]
}
{
  "error": "Failed (Invalid Sender ID)"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Sent SMS

GET https://www.5centsms.com.au/api/v5/sms

Include key-id and key-secret in the JSON body of every request.

List your sent messages, newest first.

Response fields

Field Type Description
error string Empty on success.
messages array Sent messages this page.
messages[].destination string Recipient number.
messages[].sender string Sender ID the message was sent from (mobile number, virtual number, or alphanumeric sender ID).
messages[].id string Message id.
messages[].status integer Status code (see Introduction).
messages[].status_text string Human-readable status.
messages[].message_text string Message content.
messages[].credits number Credits charged.
messages[].send_timestamp integer Epoch seconds when sent.
messages[].delivery_timestamp integer Epoch seconds when delivery confirmed.
messages[].delivery_network string Delivering network, when known.
next_page string Relative path for the next page. Omitted when there are no further results.
count integer Messages on this page.

Errors

Error HTTP Cause
Failed (Invalid Page) 400 after is not a valid 24-hex cursor.

Notes

  • See Pagination in the Introduction for the after cursor convention.
  • next_page is omitted when there are no further results.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
after24-hex cursor — the `id` of the last message on the previous page.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/sms \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/sms"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/sms", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/sms");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/sms"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/sms");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/sms", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/sms")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "messages": [
    {
      "destination": "0412333555",
      "sender": "5CENTSMS",
      "id": "683554c596937cc4b90f5cf7",
      "status": 1002,
      "status_text": "Sent (Delivery Confirmed)",
      "message_text": "Hello World",
      "credits": 1,
      "send_timestamp": 1717000000,
      "delivery_timestamp": 1717000020,
      "delivery_network": "Telstra"
    },
    {
      "destination": "0412333556",
      "sender": "0428000000",
      "id": "683554c596937cc4b90f5cf6",
      "status": 1001,
      "status_text": "Sent",
      "message_text": "Your verification code is 4821",
      "credits": 1,
      "send_timestamp": 1716999900,
      "delivery_timestamp": 0,
      "delivery_network": "Optus"
    },
    {
      "destination": "0412333557",
      "sender": "SHOPCO",
      "id": "683554c596937cc4b90f5cf5",
      "status": 1002,
      "status_text": "Sent (Delivery Confirmed)",
      "message_text": "Your order has shipped",
      "credits": 1,
      "send_timestamp": 1716999800,
      "delivery_timestamp": 1716999830,
      "delivery_network": "Vodafone"
    }
  ],
  "next_page": "/api/v5/sms?after=683554c596937cc4b90f5cf5",
  "count": 3
}
{
  "error": "",
  "messages": [
    {
      "destination": "0412333558",
      "sender": "5CENTSMS",
      "id": "683554c596937cc4b90f5cf4",
      "status": 1002,
      "status_text": "Sent (Delivery Confirmed)",
      "message_text": "Appointment reminder",
      "credits": 1,
      "send_timestamp": 1716999700,
      "delivery_timestamp": 1716999730,
      "delivery_network": "Telstra"
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get SMS Status

GET https://www.5centsms.com.au/api/v5/sms/:id

Include key-id and key-secret in the JSON body of every request.

Fetch the current status and details of a single sent message.

Response fields

Field Type Description
error string Empty on success.
message object The message (same fields as List Sent SMS).

Errors

Error HTTP Cause
Failed (Unauthorised) 400 Message not found, or not owned by this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idMessage id.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/sms/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/sms/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/sms/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/sms/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/sms/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/sms/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/sms/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/sms/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": {
    "destination": "0412333555",
    "sender": "5CENTSMS",
    "id": "683554c596937cc4b90f5cf7",
    "status": 1002,
    "status_text": "Sent (Delivery Confirmed)",
    "message_text": "Hello World",
    "credits": 1,
    "send_timestamp": 1717000000,
    "delivery_timestamp": 1717000020,
    "delivery_network": "Telstra"
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Cancel / Delete SMS

DELETE https://www.5centsms.com.au/api/v5/sms/:id

Include key-id and key-secret in the JSON body of every request.

Cancel a still-scheduled message (status 1005), or delete a sent message's record.

Response fields

Field Type Description
error string Empty on success.

Errors

Error HTTP Cause
Failed (Unauthorised) 400 Message not found, or not owned by this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idMessage id.
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/sms/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/sms/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/sms/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/sms/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/sms/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/sms/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/sms/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/sms/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": ""
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Inbound Messages

GET https://www.5centsms.com.au/api/v5/inbox

Include key-id and key-secret in the JSON body of every request.

List inbound (received) messages, newest first (50 per page).

Response fields

Field Type Description
error string Empty on success.
messages array Inbound messages this page.
messages[].id string Inbound message id.
messages[].to string Your number that received it.
messages[].from string Sender number.
messages[].message string Message content.
messages[].date integer Epoch seconds received.
messages[].contact_name string Matched contact name, when known.
next_page string Relative path for the next page. Always present on this endpoint — stop paging when messages is empty (count is 0).
count integer Messages on this page.

Errors

Error HTTP Cause
Failed (Invalid Page) 400 after is not a valid 24-hex cursor.

Notes

  • Page size is fixed at 50. Follow next_page (which carries the after cursor) until a page comes back with an empty messages array.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
after24-hex cursor — the `id` of the last message on the previous page.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/inbox \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/inbox"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/inbox", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/inbox");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/inbox"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/inbox");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/inbox", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/inbox")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "messages": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "to": "0400000000",
      "from": "0412333555",
      "message": "STOP",
      "date": 1717000000,
      "contact_name": "Jane"
    },
    {
      "id": "683554c596937cc4b90f5cf3",
      "to": "0400000000",
      "from": "0412999888",
      "message": "Yes, please book me in",
      "date": 1716999500,
      "contact_name": "Tom"
    }
  ],
  "next_page": "/api/v5/inbox?after=683554c596937cc4b90f5cf3",
  "count": 2
}
{
  "error": "",
  "messages": [],
  "next_page": "/api/v5/inbox?after=",
  "count": 0
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Inbound Message

DELETE https://www.5centsms.com.au/api/v5/inbox/:id

Include key-id and key-secret in the JSON body of every request.

Delete a single inbound message record.

Response fields

Field Type Description
error string Empty on success.

Errors

Error HTTP Cause
Failed (Unauthorised) 400 Message not found, or not owned by this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idInbound message id.
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/inbox/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/inbox/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/inbox/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/inbox/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/inbox/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/inbox/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/inbox/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/inbox/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": ""
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Opt-outs

GET https://www.5centsms.com.au/api/v5/optouts

Include key-id and key-secret in the JSON body of every request.

List numbers that have opted out, newest first (1000 per page).

Response fields

Field Type Description
error string Empty on success.
numbers array Opted-out numbers this page.
numbers[].id string Opt-out record id.
numbers[].number string Opted-out number.
numbers[].timestamp integer Epoch seconds of opt-out.
count integer Records on this page.
next_page string Relative path for the next page. Always present on this endpoint — stop paging when numbers is empty (count is 0).

Errors

Error HTTP Cause
Failed (Invalid Page) 400 after is not a valid 24-hex cursor.

Notes

  • Page size is fixed at 1000. Follow next_page (which carries the after cursor) until a page comes back with an empty numbers array.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
after24-hex cursor — the `id` of the last record on the previous page.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/optouts \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/optouts"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/optouts", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/optouts");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/optouts"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/optouts");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/optouts", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/optouts")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "numbers": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "number": "0412333555",
      "timestamp": 1717000000
    },
    {
      "id": "683554c596937cc4b90f5cf2",
      "number": "0412333777",
      "timestamp": 1716999000
    }
  ],
  "count": 2,
  "next_page": "/api/v5/optouts?after=683554c596937cc4b90f5cf2"
}
{
  "error": "",
  "numbers": [],
  "count": 0,
  "next_page": "/api/v5/optouts?after="
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Opt-out

DELETE https://www.5centsms.com.au/api/v5/optouts/:number

Include key-id and key-secret in the JSON body of every request.

Remove a number from your opt-out list.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
numberThe opted-out number to remove.
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/optouts/:number \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/optouts/:number"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/optouts/:number", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/optouts/:number");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/optouts/:number"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/optouts/:number");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/optouts/:number", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/optouts/:number")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Number removed."
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Status Codes

GET https://www.5centsms.com.au/api/v5/statuslist

Include key-id and key-secret in the JSON body of every request.

Return the full catalogue of message status codes and their descriptions. The list is global (not account-specific) and matches the codes returned in the status field of GET /sms and GET /sms/{id} and the descriptions used in the Dashboard.

Authentication is still required (key-id / key-secret in the request body) so the call is rate-limited and logged like every other v5 endpoint.

Response fields

Field Type Description
error string Empty on success.
status_codes array One object per status code.
status_codes[].code number Numeric status code (e.g. 1002).
status_codes[].description string Human-readable description (e.g. Sent (Delivery Confirmed)).

Errors

Error HTTP Cause
Unsupported method. Please see our API Docs 400 The endpoint was called with POST or DELETE.

Authentication errors are documented once in the collection intro (401 auth-error table).

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/statuslist \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/statuslist"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/statuslist", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/statuslist");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/statuslist"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/statuslist");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/statuslist", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/statuslist")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "status_codes": [
    { "code": 1000, "description": "Sending... (Queued)" },
    { "code": 1001, "description": "Sent" },
    { "code": 1002, "description": "Sent (Delivery Confirmed)" }
  ]
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Conversations

GET https://www.5centsms.com.au/api/v5/conversations?per_page=50

Include key-id and key-secret in the JSON body of every request.

List the account's two-way SMS conversations, newest activity first, cursor-paginated. Requires Conversations (threads) enabled and at least one virtual mobile number (VMN).

Response fields

Field Type Description
error string Empty on success.
conversations array One entry per conversation, newest activity first.
conversations[].id string Conversation id.
conversations[].remote_number string Contact number, normalised to 61 international form.
conversations[].contact_name string Matched contact name, or empty.
conversations[].last_message_at integer Epoch seconds of the latest message.
conversations[].unread boolean Unread flag.
conversations[].has_inbound boolean True once the contact has replied.
conversations[].last_local_number string The VMN this thread is on.
conversations[].created_at integer Epoch seconds the conversation began.
next_cursor string or null Pass as before for the next page; null on the last page.
count integer Conversations on this page.

Errors

Error HTTP Cause
Conversations are not enabled for this account. Enable Conversations in your 5cSMS dashboard settings, or contact support to turn on two-way messaging. 400 Account lacks the ENABLE_THREADS flag. Response also carries error_code: "threads_disabled".
Conversations require a dedicated virtual mobile number (VMN). Add a VMN in your 5cSMS dashboard under Virtual Numbers, then inbound replies will thread automatically. 400 Threads on but the account has no VMN. Response also carries error_code: "no_vmn".
Failed (Method Not Supported) 400 A POST or DELETE was sent to any /conversations route. The endpoint is read-only.

Notes

  • Gate failures return an extra error_code field (threads_disabled or no_vmn) so an integrator can branch programmatically.
  • Follow next_cursor (passed back as the before parameter) until it is null.
  • q matches digits in the remote number; replies=1 and unread=1 are independent filters.
  • To send, use POST /api/v5/sms. Replies thread into the conversation automatically.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
beforeCursor from a previous response's next_cursor. Omit for the first page.
per_page50Page size, max 200. Default 50.
qDigit search on the contact number.
replies1Set to 1 to return only conversations that have an inbound reply.
unread1Set to 1 to return only unread conversations.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/conversations?per_page=50 \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations?per_page=50"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/conversations?per_page=50", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/conversations?per_page=50");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations?per_page=50"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/conversations?per_page=50");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations?per_page=50", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/conversations?per_page=50")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "conversations": [
    {
      "id": "66b0a1c2d3e4f5a6b7c8d9e0",
      "remote_number": "61412345678",
      "contact_name": "Jane Smith",
      "last_message_at": 1749600120,
      "unread": true,
      "has_inbound": true,
      "last_local_number": "61480000000",
      "created_at": 1749000000
    }
  ],
  "next_cursor": "1749600120_66b0a1c2d3e4f5a6b7c8d9e0",
  "count": 1
}
{
  "error": "",
  "conversations": [
    {
      "id": "66a90b1c2d3e4f5a6b7c8d90",
      "remote_number": "61412000111",
      "contact_name": "",
      "last_message_at": 1748900000,
      "unread": false,
      "has_inbound": false,
      "last_local_number": "61480000000",
      "created_at": 1748900000
    }
  ],
  "next_cursor": null,
  "count": 1
}
{
  "error": "Conversations are not enabled for this account. Enable Conversations in your 5cSMS dashboard settings, or contact support to turn on two-way messaging.",
  "error_code": "threads_disabled"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Resolve Conversation by Number

GET https://www.5centsms.com.au/api/v5/conversations?number=0412345678

Include key-id and key-secret in the JSON body of every request.

Resolve a single conversation by the remote phone number. The number is normalised to 61 international form, so 04..., +61..., and 61... inputs all resolve.

Response fields

Field Type Description
error string Empty on success.
conversation object or null The matching conversation summary (same fields as a List entry, plus contact_name), or null when the number has no thread.

Errors

Error HTTP Cause
Conversations are not enabled for this account. Enable Conversations in your 5cSMS dashboard settings, or contact support to turn on two-way messaging. 400 Account lacks the ENABLE_THREADS flag. Response also carries error_code: "threads_disabled".
Conversations require a dedicated virtual mobile number (VMN). Add a VMN in your 5cSMS dashboard under Virtual Numbers, then inbound replies will thread automatically. 400 Threads on but the account has no VMN. Response also carries error_code: "no_vmn".

Notes

  • A number with no conversation returns {"error": "", "conversation": null}. This is a success, not an error.
  • Gate failures return an extra error_code field (threads_disabled or no_vmn).

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
number0412345678Required. Recipient MSISDN in 04..., +61..., or 61... form; normalised to 61 international form.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/conversations?number=0412345678 \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations?number=0412345678"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/conversations?number=0412345678", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/conversations?number=0412345678");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations?number=0412345678"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/conversations?number=0412345678");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations?number=0412345678", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/conversations?number=0412345678")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "conversation": {
    "id": "66b0a1c2d3e4f5a6b7c8d9e0",
    "remote_number": "61412345678",
    "contact_name": "Jane Smith",
    "last_message_at": 1749600120,
    "unread": true,
    "has_inbound": true,
    "last_local_number": "61480000000",
    "created_at": 1749000000
  }
}
{
  "error": "",
  "conversation": null
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Conversation Messages

GET https://www.5centsms.com.au/api/v5/conversations/:id

Include key-id and key-secret in the JSON body of every request.

Fetch the conversation summary plus the most recent page of messages (oldest to newest within the page). Opening a conversation marks it read.

Response fields

Field Type Description
error string Empty on success.
conversation object Conversation summary, including contact_name.
messages array Messages, oldest to newest within the page.
messages[].id string Message id.
messages[].message string Message text.
messages[].timestamp integer Epoch seconds.
messages[].type string MT (sent) or MO (received).
messages[].status integer or null Delivery status code (MT only). See the message status table in the Introduction.
messages[].status_text string Human-readable status, e.g. "Delivered" (MT only).
messages[].scheduled boolean Present and true when the message is scheduled (MT only).
messages[].cancelled boolean Present and true when the message was cancelled (MT only).
messages[].cancellable boolean Present and true when the message can still be cancelled (MT only).
messages[].images array Image URLs (MMS only).
has_more boolean True when older messages remain (page back with action=older).
oldest_mo_ts integer Oldest received-message watermark on this page (use as before_mo).
oldest_mt_ts integer Oldest sent-message watermark on this page (use as before_mt).
newest_mo_ts integer Newest received-message watermark (use as since_mo when polling).
newest_mt_ts integer Newest sent-message watermark (use as since_mt when polling).

Errors

Error HTTP Cause
Conversations are not enabled for this account. Enable Conversations in your 5cSMS dashboard settings, or contact support to turn on two-way messaging. 400 Account lacks the ENABLE_THREADS flag. Response also carries error_code: "threads_disabled".
Conversations require a dedicated virtual mobile number (VMN). Add a VMN in your 5cSMS dashboard under Virtual Numbers, then inbound replies will thread automatically. 400 Threads on but the account has no VMN. Response also carries error_code: "no_vmn".
Failed (Conversation Not Found) 400 The id was not found or is not owned by this account.

Notes

  • Side effect: opening a conversation marks it read (unread becomes false).
  • Page back through history with the Page Older Messages request, and fetch new messages with the Poll Conversation request.
  • To send a reply, use POST /api/v5/sms. Replies thread into the conversation automatically.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
limit50Page size, 1 to 100. Default 50.

Path variables

VariableExampleDescription
id66b0a1c2d3e4f5a6b7c8d9e0Conversation id.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/conversations/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/conversations/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/conversations/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/conversations/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/conversations/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "conversation": {
    "id": "66b0a1c2d3e4f5a6b7c8d9e0",
    "remote_number": "61412345678",
    "contact_name": "Jane Smith",
    "last_message_at": 1749600120,
    "unread": false,
    "has_inbound": true,
    "last_local_number": "61480000000",
    "created_at": 1749000000
  },
  "messages": [
    {
      "id": "66a0a1c2d3e4f5a6b7c8d9e0",
      "message": "Your booking is confirmed",
      "timestamp": 1749600060,
      "type": "MT",
      "status": 1002,
      "status_text": "Sent (Delivery Confirmed)"
    },
    {
      "id": "66a1a1c2d3e4f5a6b7c8d9e0",
      "message": "Yes please",
      "timestamp": 1749600120,
      "type": "MO"
    }
  ],
  "has_more": false,
  "oldest_mo_ts": 1749600120,
  "oldest_mt_ts": 1749600060,
  "newest_mo_ts": 1749600120,
  "newest_mt_ts": 1749600060
}
{
  "error": "Failed (Conversation Not Found)"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Poll Conversation

GET https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060

Include key-id and key-secret in the JSON body of every request.

Return only messages newer than the supplied watermarks. Use the newest_mo_ts and newest_mt_ts from the initial load (or the previous poll) as since_mo and since_mt. A poll that returns new messages marks the conversation read.

Response fields

Field Type Description
error string Empty on success.
messages array Only messages newer than the watermarks (same message shape as Get Conversation Messages).
now integer Server epoch seconds, for poll cadence.

Errors

Error HTTP Cause
Conversations are not enabled for this account. Enable Conversations in your 5cSMS dashboard settings, or contact support to turn on two-way messaging. 400 Account lacks the ENABLE_THREADS flag. Response also carries error_code: "threads_disabled".
Conversations require a dedicated virtual mobile number (VMN). Add a VMN in your 5cSMS dashboard under Virtual Numbers, then inbound replies will thread automatically. 400 Threads on but the account has no VMN. Response also carries error_code: "no_vmn".
Failed (Conversation Not Found) 400 The id was not found or is not owned by this account.
Failed (Invalid Watermark) 400 since_mo or since_mt is missing or not a digit string.

Notes

  • Side effect: a poll that returns one or more new messages marks the conversation read.
  • since_mo and since_mt must be integer epoch-second values.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
actionpollRequired. Set to poll.
since_mo1749600120Required. Received-message watermark (epoch seconds); use the prior response's newest_mo_ts.
since_mt1749600060Required. Sent-message watermark (epoch seconds); use the prior response's newest_mt_ts.

Path variables

VariableExampleDescription
id66b0a1c2d3e4f5a6b7c8d9e0Conversation id.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060 \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "messages": [
    {
      "id": "66a2a1c2d3e4f5a6b7c8d9e0",
      "message": "On my way",
      "timestamp": 1749600300,
      "type": "MO"
    }
  ],
  "now": 1749600305
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Page Older Messages

GET https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060

Include key-id and key-secret in the JSON body of every request.

Page back through history older than the supplied cursors. Use the oldest_mo_ts and oldest_mt_ts from the previous page as before_mo and before_mt.

Response fields

Field Type Description
error string Empty on success.
messages array The older page (same message shape as Get Conversation Messages).
has_more boolean True when still-older messages remain.
oldest_mo_ts integer Oldest received-message watermark on this page (use as the next before_mo).
oldest_mt_ts integer Oldest sent-message watermark on this page (use as the next before_mt).

Errors

Error HTTP Cause
Conversations are not enabled for this account. Enable Conversations in your 5cSMS dashboard settings, or contact support to turn on two-way messaging. 400 Account lacks the ENABLE_THREADS flag. Response also carries error_code: "threads_disabled".
Conversations require a dedicated virtual mobile number (VMN). Add a VMN in your 5cSMS dashboard under Virtual Numbers, then inbound replies will thread automatically. 400 Threads on but the account has no VMN. Response also carries error_code: "no_vmn".
Failed (Conversation Not Found) 400 The id was not found or is not owned by this account.
Failed (Invalid Watermark) 400 before_mo or before_mt is missing or not a digit string.

Notes

  • This request does not mark the conversation read (unlike the initial load and a poll that returns new messages).
  • Keep paging with the returned oldest_mo_ts / oldest_mt_ts until has_more is false — the final page comes back with an empty messages array and both watermarks 0.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
actionolderRequired. Set to older.
before_mo1749600120Required. Use the prior response's oldest_mo_ts.
before_mt1749600060Required. Use the prior response's oldest_mt_ts.
limit50Page size, 1 to 100. Default 50.

Path variables

VariableExampleDescription
id66b0a1c2d3e4f5a6b7c8d9e0Conversation id.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060 \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "messages": [
    {
      "id": "669f0a1c2d3e4f5a6b7c8d90",
      "message": "Earlier message",
      "timestamp": 1749500050,
      "type": "MO"
    }
  ],
  "has_more": true,
  "oldest_mo_ts": 1749500050,
  "oldest_mt_ts": 1749500000
}
{
  "error": "",
  "messages": [],
  "has_more": false,
  "oldest_mo_ts": 0,
  "oldest_mt_ts": 0
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Send Email

POST https://api.dingomail.com.au/api/v5/email

Include key-id and key-secret in the JSON body of every request.

Send a transactional email. The sender must be on a registered, validated domain (see Email Domains).

Request body parameters

Field Type Required Description
SenderEmail string Yes From address. Must be on a registered, validated domain.
Subject string Yes Email subject.
Text string Yes Plain-text body.
Html string No HTML body. Defaults to Text if omitted.
SenderName string No Display name for the From address.
Recipient string or array Conditional To recipient(s). At least one of Recipient / CC / BCC is required; combined max 50.
CC string or array Conditional CC recipient(s).
BCC string or array Conditional BCC recipient(s).
ReplyTo string No Reply-To address.
Attachments array No Array of {url, filename?}. Requires the DINGO_ATTACHMENT account flag; max 5.
test boolean No Sandbox mode. When true, the request is fully validated (sender authorization, recipient limits, attachments) and a message record is created, but the email is not sent and does not consume email quota. Assessed as true unless the parameter is omitted or is one of these values: false, "false", 0, "0".

Test mode: pass test: true to validate an email end-to-end without sending or billing. A v2_emails record is still created (visible via GET /api/v5/email with Status: test), but SES is never called.

Response fields

Field Type Description
error string Empty on success.
messages array One entry per send.
messages[].Id string Email id.
messages[].Status string Email status.
messages[].Recipients object {To, CC, TotalCount} — BCC omitted for privacy.

Errors

Error HTTP Cause
Email not enabled. Please contact us. 400 Email is not enabled on this account.
Required parameter: {field} missing 400 A required field (SenderEmail / Subject / Text) is missing.
Required parameter: At least one of Recipient, CC, or BCC must be provided 400 No recipient supplied.
Too many recipients. Maximum 50 allowed, got {n}. 400 Combined recipients exceed 50.
Invalid email addresses: {list} 400 One or more recipient addresses are malformed.
Invalid Sender Email 400 SenderEmail is malformed.
Invalid Sender Domain 400 Sender domain is not registered or validated on this account.
Invalid Sender Domain or Mailbox 400 For hosted-mailbox senders, the address is not one of the account's active mailboxes.
Attachments not enabled for this account 403 Attachments require the DINGO_ATTACHMENT flag.
Maximum {n} attachments allowed 400 Too many attachments (max 5).
Each attachment must have a url field 400 An attachment entry is missing url.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/email \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome",
    "Text": "Hello there",
    "Html": "<p>Hello there</p>",
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/email"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome",
    "Text": "Hello there",
    "Html": "<p>Hello there</p>",
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome",
    "Text": "Hello there",
    "Html": "<p>Hello there</p>",
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
});

const req = https.request("https://api.dingomail.com.au/api/v5/email", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/email");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome",
    "Text": "Hello there",
    "Html": "<p>Hello there</p>",
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome",
    "Text": "Hello there",
    "Html": "<p>Hello there</p>",
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/email"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.dingomail.com.au/api/v5/email");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""SenderEmail"": ""news@mail.example.com"",
    ""SenderName"": ""Example"",
    ""Subject"": ""Welcome"",
    ""Text"": ""Hello there"",
    ""Html"": ""<p>Hello there</p>"",
    ""Recipient"": ""jane@example.com"",
    ""ReplyTo"": ""support@example.com""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome",
    "Text": "Hello there",
    "Html": "<p>Hello there</p>",
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/email", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/email")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome",
    "Text": "Hello there",
    "Html": "<p>Hello there</p>",
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "messages": [
    {
      "Id": "683554c596937cc4b90f5cf7",
      "Status": "queued",
      "Recipients": {
        "To": [
          "jane@example.com"
        ],
        "CC": [],
        "TotalCount": 1
      }
    }
  ]
}
{
  "error": "",
  "messages": [
    {
      "Id": "6650f1a2b3c4d5e6f7a8b9c0",
      "Status": "test",
      "Recipients": {
        "To": [
          "someone@example.com"
        ],
        "CC": [],
        "TotalCount": 1
      }
    }
  ]
}
{
  "error": "Invalid Sender Domain"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Emails

GET https://api.dingomail.com.au/api/v5/email

Include key-id and key-secret in the JSON body of every request.

List sent emails, newest first.

Response fields

Field Type Description
error string Empty on success.
emails array Emails this page.
emails[].id string Email id.
emails[].status string Email status.
emails[].from string From address.
emails[].sender_name string From display name.
emails[].to array To recipients.
emails[].cc array CC recipients.
emails[].subject string Subject.
emails[].created_at integer Epoch seconds created.
emails[].method string Send method.
count integer Emails on this page.
next_page string Relative path for the next page — present only when count >= limit.

Errors

Error HTTP Cause
Invalid after parameter 400 after is not a valid 24-hex cursor.
Invalid limit parameter 400 limit is outside 1–100.

Notes

  • next_page appears only when a full page is returned (count >= limit); follow it until it is absent. It echoes any non-default limit. The paging examples below use limit=2 to stay short.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
after24-hex cursor — the `id` of the last email on the previous page.
limit20Page size, 1–100. Default 20.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/email \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/email"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://api.dingomail.com.au/api/v5/email", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/email");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/email"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.dingomail.com.au/api/v5/email");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/email", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/email")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "emails": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "status": "sent",
      "from": "news@mail.example.com",
      "sender_name": "Example",
      "to": [
        "jane@example.com"
      ],
      "cc": [],
      "subject": "Welcome",
      "created_at": 1717000000,
      "method": "api"
    },
    {
      "id": "683554c596937cc4b90f5cf5",
      "status": "sent",
      "from": "news@mail.example.com",
      "sender_name": "Example",
      "to": [
        "tom@example.com"
      ],
      "cc": [],
      "subject": "Your receipt",
      "created_at": 1716999000,
      "method": "api"
    }
  ],
  "count": 2,
  "next_page": "/api/v5/email?after=683554c596937cc4b90f5cf5&limit=2"
}
{
  "error": "",
  "emails": [
    {
      "id": "683554c596937cc4b90f5cf1",
      "status": "sent",
      "from": "news@mail.example.com",
      "sender_name": "Example",
      "to": [
        "amy@example.com"
      ],
      "cc": [],
      "subject": "Order shipped",
      "created_at": 1716998000,
      "method": "api"
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Email

GET https://api.dingomail.com.au/api/v5/email/:id

Include key-id and key-secret in the JSON body of every request.

Fetch a single email, including its full text and HTML bodies.

Response fields

Field Type Description
error string Empty on success.
email object id, status, from, sender_name, to, cc, subject, text, html, reply_to, created_at, method.

Errors

Error HTTP Cause
Invalid email ID 400 id is not a valid 24-hex id.
Email not found 400 No such email, or not owned by this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idEmail id.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/email/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/email/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://api.dingomail.com.au/api/v5/email/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/email/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/email/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.dingomail.com.au/api/v5/email/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/email/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/email/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "email": {
    "id": "683554c596937cc4b90f5cf7",
    "status": "sent",
    "from": "news@mail.example.com",
    "sender_name": "Example",
    "to": [
      "jane@example.com"
    ],
    "cc": [],
    "subject": "Welcome",
    "text": "Hello there",
    "html": "<p>Hello there</p>",
    "reply_to": "support@example.com",
    "created_at": 1717000000,
    "method": "api"
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Inbound Emails

GET https://api.dingomail.com.au/api/v5/inboundemail

Include key-id and key-secret in the JSON body of every request.

List received (inbound) emails for the account, newest first. Returns both hosted-mailbox-routed and custom-domain-routed inbound mail; pass mailbox_address to restrict to one hosted mailbox.

Request body

Field Type Required Description
key-id string Yes API key id (see intro auth).
key-secret string Yes API key secret (see intro auth).

Query parameters

Field Type Required Description
after string No 24-hex cursor; id of the last row on the previous page.
limit integer No Page size 1–1000, default 20.
mailbox_address string No Restrict to one hosted mailbox address.

Response fields

Field Type Description
error string Empty on success.
emails array Inbound emails this page, newest first.
emails[].id string Inbound email id.
emails[].from string Sender address.
emails[].to string Raw To header the mail was delivered to.
emails[].subject string Subject.
emails[].has_attachments boolean True if the email has any attachment (inline or file).
emails[].mailbox_address string Present only for hosted-mailbox-routed inbound.
emails[].created_at integer Epoch seconds received.
count integer Emails on this page.
next_page string Relative path for the next page — present only when count >= limit.

Errors

Error HTTP Cause
Invalid after parameter 400 after is not a valid 24-hex cursor.
Invalid limit parameter 400 limit is non-numeric.
Invalid mailbox_address parameter 400 mailbox_address is not a string.
Unsupported method 400 The route was called with POST or DELETE (read-only).

Notes

  • next_page appears only when a full page is returned (count >= limit); follow it until it is absent. It echoes any non-default limit and the mailbox_address filter. The paging examples below use limit=2 to stay short.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
after24-hex cursor — the `id` of the last inbound email on the previous page.
limit20Page size, 1–1000. Default 20.
mailbox_addressOptional. Restrict to inbound routed to this hosted mailbox address (lowercased). Omit for all inbound.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/inboundemail \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/inboundemail"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://api.dingomail.com.au/api/v5/inboundemail", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/inboundemail");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/inboundemail"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.dingomail.com.au/api/v5/inboundemail");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/inboundemail", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/inboundemail")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "emails": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "from": "jane@example.com",
      "to": "support@mail.example.com",
      "subject": "Re: Welcome",
      "has_attachments": false,
      "created_at": 1717000000
    },
    {
      "id": "683554c596937cc4b90f5cf5",
      "from": "tom@example.com",
      "to": "hello@mail.example.com",
      "subject": "Invoice attached",
      "has_attachments": true,
      "mailbox_address": "hello@mail.example.com",
      "created_at": 1716999000
    }
  ],
  "count": 2,
  "next_page": "/api/v5/inboundemail?after=683554c596937cc4b90f5cf5&limit=2"
}
{
  "error": "",
  "emails": [
    {
      "id": "683554c596937cc4b90f5cf1",
      "from": "amy@example.com",
      "to": "support@mail.example.com",
      "subject": "Question about my order",
      "has_attachments": false,
      "created_at": 1716998000
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Inbound Email

GET https://api.dingomail.com.au/api/v5/inboundemail/:id

Include key-id and key-secret in the JSON body of every request.

Fetch a single received email, including its full text and HTML bodies and attachment metadata. Scoped to the owning account.

Request body

Field Type Required Description
key-id string Yes API key id (see intro auth).
key-secret string Yes API key secret (see intro auth).

Path parameters

Field Type Required Description
id string Yes 24-hex inbound email id.

Response fields

Field Type Description
error string Empty on success.
email.id string Inbound email id.
email.from string Sender address.
email.to string Raw To header.
email.subject string Subject.
email.text string Plain-text body.
email.html string HTML body (inline cid: images already rewritten to S3 URLs).
email.attachments array Attachment metadata.
email.attachments[].filename string File name.
email.attachments[].content_type string MIME type.
email.attachments[].size integer Bytes.
email.attachments[].url string Presigned S3 download URL, valid for 1 hour.
email.attachments[].content_id string MIME Content-ID (inline images).
email.attachments[].is_inline boolean True for embedded inline images.
email.mailbox_address string Present only for hosted-mailbox-routed inbound.
email.mailbox_id string Present only with mailbox_address.
email.created_at integer Epoch seconds received.

Errors

Error HTTP Cause
Invalid inbound email ID 400 id is not a valid 24-hex id.
Inbound email not found 400 No such inbound email, or not owned by this account.
Unsupported method 400 The route was called with POST or DELETE (read-only).

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idInbound email id.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/inboundemail/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/inboundemail/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://api.dingomail.com.au/api/v5/inboundemail/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/inboundemail/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/inboundemail/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.dingomail.com.au/api/v5/inboundemail/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/inboundemail/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/inboundemail/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "email": {
    "id": "683554c596937cc4b90f5cf7",
    "from": "jane@example.com",
    "to": "support@mail.example.com",
    "subject": "Re: Welcome",
    "text": "Thanks!",
    "html": "<p>Thanks!</p>",
    "attachments": [],
    "created_at": 1717000000
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Balance

GET https://www.5centsms.com.au/api/v5/balance

Include key-id and key-secret in the JSON body of every request.

Get your account's credit balance and billing mode.

Response fields

Field Type Description
error string Empty on success.
balance object Balance details.
balance.postpaid boolean True if the account is postpaid.
balance.credits number Available credits.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/balance \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/balance"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/balance", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/balance");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/balance"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/balance");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/balance", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/balance")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "balance": {
    "postpaid": false,
    "credits": 1234.5
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Pre-warm Send Queue

POST https://www.5centsms.com.au/api/v5/prewarm

Include key-id and key-secret in the JSON body of every request.

Pre-warm the send queue ahead of a large campaign. Requires the QUEUE_PREWARM account flag; usable once per 60 minutes.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.

Errors

Error HTTP Cause
Account does not have queue pre-warming enabled 400 QUEUE_PREWARM flag not set on the account.
Queue was already pre-warmed recently. Please wait {n} minutes before trying again. 400 Pre-warmed within the last 60 minutes.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/prewarm \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/prewarm"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/prewarm", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/prewarm");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/prewarm"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/prewarm");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/prewarm", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/prewarm")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Queue pre-warming initiated."
}
{
  "error": "Account does not have queue pre-warming enabled"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Login

POST https://www.5centsms.com.au/api/v5/logins

Include key-id and key-secret in the JSON body of every request.

Create (or re-invite) a sub-login on your account.

Request body parameters

Field Type Required Description
name string Yes Login's display name.
email string Yes Login's email address.
role string No One of admin, manager, sender, reporting. Default admin.

Response fields

Field Type Description
error string Empty on success.
login_id string The login's id.
is_new boolean True if a new login was created.
message string Confirmation message.

Errors

Error HTTP Cause
Missing required field: name 400 name not supplied.
Missing required field: email 400 email not supplied.
Invalid email address 400 email is malformed.
Invalid role. Must be one of: admin, manager, sender, reporting 400 role is not an allowed value.
Login already exists on this account 400 A login with that email already exists here.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/logins \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/logins"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
});

const req = https.request("https://www.5centsms.com.au/api/v5/logins", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/logins");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/logins"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/logins");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""name"": ""Jane Smith"",
    ""email"": ""jane@example.com"",
    ""role"": ""admin""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/logins", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/logins")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "login_id": "683554c596937cc4b90f5cf7",
  "is_new": true,
  "message": "Login created"
}
{
  "error": "Invalid role. Must be one of: admin, manager, sender, reporting"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Logins

GET https://www.5centsms.com.au/api/v5/logins

Include key-id and key-secret in the JSON body of every request.

List all logins on your account.

Response fields

Field Type Description
error string Empty on success.
logins array Logins on the account.
logins[].login_id string Login id.
logins[].name string Display name.
logins[].email string Email address.
logins[].role string Role.
count integer Number of logins.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/logins \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/logins"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/logins", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/logins");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/logins"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/logins");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/logins", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/logins")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "logins": [
    {
      "login_id": "683554c596937cc4b90f5cf7",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "admin"
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Change Login Role

POST https://www.5centsms.com.au/api/v5/logins/:login_id

Include key-id and key-secret in the JSON body of every request.

Change a login's role.

Request body parameters

Field Type Required Description
action string Yes Must be change_role.
role string Yes One of admin, manager, sender, reporting.

Response fields

Field Type Description
error string Empty on success.
login_id string The login's id.
role string The new role.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid login_id format 400 login_id is not a valid id.
Missing required field: role 400 role not supplied.
Invalid role. Must be one of: admin, manager, sender, reporting 400 role is not an allowed value.
Login not found on this account 400 No such login on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
login_idLogin id.
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/logins/:login_id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "change_role",
    "role": "manager"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/logins/:login_id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "change_role",
    "role": "manager"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "change_role",
    "role": "manager"
});

const req = https.request("https://www.5centsms.com.au/api/v5/logins/:login_id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/logins/:login_id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "change_role",
    "role": "manager"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "change_role",
    "role": "manager"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/logins/:login_id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/logins/:login_id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""action"": ""change_role"",
    ""role"": ""manager""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "change_role",
    "role": "manager"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/logins/:login_id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/logins/:login_id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "change_role",
    "role": "manager"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "login_id": "683554c596937cc4b90f5cf7",
  "role": "manager",
  "message": "Role updated"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Login

DELETE https://www.5centsms.com.au/api/v5/logins/:login_id

Include key-id and key-secret in the JSON body of every request.

Remove a login from your account.

Response fields

Field Type Description
error string Empty on success.
login_id string The removed login's id.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid login_id format 400 login_id is not a valid id.
Login not found on this account 400 No such login on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
login_idLogin id.
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/logins/:login_id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/logins/:login_id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/logins/:login_id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/logins/:login_id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/logins/:login_id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/logins/:login_id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/logins/:login_id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/logins/:login_id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "login_id": "683554c596937cc4b90f5cf7",
  "message": "Login removed from account"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create campaign

POST https://www.5centsms.com.au/api/v5/campaigns

Include key-id and key-secret in the JSON body of every request.

Create an SMS, email, or combined campaign. A campaign is created in DRAFT status. In a single call you can also set the campaign's content, add recipients inline, and send or schedule it — or do each step separately with the other endpoints in this folder.

Campaigns are an account resource on the 5c SMS host ({{base_url_sms}}) for both channels.

Request body parameters

Field Type Required Description
type string No sms, email, or both. Default sms.
title string No Campaign title.
sms_sender_id string No SMS sender ID or virtual number (SMS / both).
sms_body string No SMS message body (SMS / both).
sms_optout_enabled boolean No Append an opt-out link to the SMS.
sms_unicode_enabled boolean No Send the SMS as unicode. Requires the UTF16 account feature.
sender_email string No From address; must be at one of your validated sending domains (email / both).
sender_name string No From name (email / both).
subject string No Email subject line (email / both).
email_body string No Email HTML body (email / both).
email_text string No Email plain-text body (email / both).
numbers string or array No Phone numbers to add as individual recipients. Array, or a comma/newline-delimited string. Max 100 individual recipients per call (numbers + emails combined).
emails string or array No Email addresses to add as individual recipients. Same format and cap as numbers.
contact_list_ids string or array No Contact list ids to add as recipient sources. Each must be a 24-char hex id you own.
send boolean No If true, send the campaign immediately after it is built.
schedule integer or string No Unix timestamp or a strtotime-parseable string. Schedules the send for that time; supplying it implies send.

Response fields

Field Type Description
error string Empty on success. Carries the send error if an inline send/schedule failed its gating (the campaign is still created).
campaign_id string The new campaign's id.
status string DRAFT, or SENDING / SCHEDULED if sent inline.
recipient_count integer Recipients currently on the campaign.
recipients_added integer Individual recipients added (present only when inline recipients were supplied).
recipient_errors array Per-recipient errors for skipped individuals (present only when inline recipients were supplied).
send object The send result (present only when send/schedule was requested): error, campaign_id, status, message.

Errors

Error HTTP Cause
Invalid campaign type 400 type is not sms, email, or both.
Unicode requires the UTF16 feature on your account 400 sms_unicode_enabled set without the UTF16 account feature.

Note — inline send is not atomic. When you pass send/schedule and the send gating fails (see the Send / schedule campaign endpoint for those errors), the campaign persists as DRAFT, the top-level error carries the send failure, and send holds the detail. Fix the issue and call the Send endpoint — do not re-create.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "sms",
    "title": "July promo",
    "sms_sender_id": "EXAMPLE",
    "sms_body": "Hello from Acme!",
    "sms_optout_enabled": true,
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ],
    "send": false
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "sms",
    "title": "July promo",
    "sms_sender_id": "EXAMPLE",
    "sms_body": "Hello from Acme!",
    "sms_optout_enabled": true,
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ],
    "send": false
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "sms",
    "title": "July promo",
    "sms_sender_id": "EXAMPLE",
    "sms_body": "Hello from Acme!",
    "sms_optout_enabled": true,
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ],
    "send": false
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "sms",
    "title": "July promo",
    "sms_sender_id": "EXAMPLE",
    "sms_body": "Hello from Acme!",
    "sms_optout_enabled": true,
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ],
    "send": false
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "sms",
    "title": "July promo",
    "sms_sender_id": "EXAMPLE",
    "sms_body": "Hello from Acme!",
    "sms_optout_enabled": true,
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ],
    "send": false
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/campaigns");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""type"": ""sms"",
    ""title"": ""July promo"",
    ""sms_sender_id"": ""EXAMPLE"",
    ""sms_body"": ""Hello from Acme!"",
    ""sms_optout_enabled"": true,
    ""contact_list_ids"": [
        ""683554c596937cc4b90f5cf7""
    ],
    ""send"": false
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "sms",
    "title": "July promo",
    "sms_sender_id": "EXAMPLE",
    "sms_body": "Hello from Acme!",
    "sms_optout_enabled": true,
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ],
    "send": false
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "sms",
    "title": "July promo",
    "sms_sender_id": "EXAMPLE",
    "sms_body": "Hello from Acme!",
    "sms_optout_enabled": true,
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ],
    "send": false
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "status": "DRAFT",
  "recipient_count": 240,
  "recipients_added": 0,
  "recipient_errors": []
}
{
  "error": "Invalid campaign type"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List campaigns

GET https://www.5centsms.com.au/api/v5/campaigns

Include key-id and key-secret in the JSON body of every request.

List your account's campaigns, most-recent-first. Returns up to the 200 most recent campaigns; older campaigns are purged 365 days after creation.

Response fields

Field Type Description
error string Empty on success.
campaigns array Campaigns, newest first.
campaigns[].campaign_id string Campaign id.
campaigns[].title string Campaign title.
campaigns[].status string DRAFT, SCHEDULED, SENDING, or SENT.
campaigns[].type array Channels: any of sms, email.
campaigns[].recipient_count integer Recipients on the campaign.
campaigns[].schedule integer Scheduled send time (unix), or null.
count integer Number of campaigns returned.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/campaigns \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/campaigns");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/campaigns", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "campaigns": [
    {
      "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "title": "July promo",
      "status": "SENT",
      "type": ["sms"],
      "recipient_count": 240,
      "schedule": null
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get campaign

GET https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Fetch one campaign: its settings, recipients, and combined SMS/email delivery stats.

Response fields

Field Type Description
error string Empty on success.
campaign_id string Campaign id.
title string Campaign title.
status string DRAFT, SCHEDULED, SENDING, or SENT.
type array Channels: any of sms, email.
recipient_count integer Recipients on the campaign.
schedule integer Scheduled send time (unix), or null.
sms object SMS settings (present for sms/both): sender_id, body, optout_enabled, unicode_enabled.
email object Email settings (present for email/both): sender_email, sender_name, subject, has_body.
recipients array Recipient rows: id, type (individual/contact_list), and either recipient_type+value or contact_list_id+contact_list_name+contact_list_count, plus created.
stats object Delivery stats: type (sms/email/both/none); sms and/or email count objects.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "title": "July promo",
  "status": "SENT",
  "type": ["sms"],
  "recipient_count": 240,
  "schedule": null,
  "sms": {
    "sender_id": "EXAMPLE",
    "body": "Hello from Acme!",
    "optout_enabled": true,
    "unicode_enabled": false
  },
  "recipients": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c11",
      "type": "contact_list",
      "contact_list_id": "683554c596937cc4b90f5cf7",
      "contact_list_name": "VIP",
      "contact_list_count": 240,
      "created": 1721700000
    }
  ],
  "stats": {
    "type": "sms",
    "sms": { "total": 240, "queued": 0, "sent": 40, "delivered": 195, "failed": 5 }
  }
}
{
  "error": "Campaign not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Update campaign

POST https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Update a draft campaign's settings. Only campaigns in DRAFT status can be edited. Supply action: update plus any of the content fields; only the fields you send are changed.

Request body parameters

Field Type Required Description
action string Yes Must be update.
type string No sms, email, or both.
title string No Campaign title.
sms_sender_id string No SMS sender ID or virtual number.
sms_body string No SMS message body.
sms_optout_enabled boolean No Append an opt-out link to the SMS.
sms_unicode_enabled boolean No Send as unicode. Requires the UTF16 account feature.
sender_email string No From address; must be at one of your validated domains.
sender_name string No From name.
subject string No Email subject line.
email_body string No Email HTML body.
email_text string No Email plain-text body.

Response fields

Field Type Description
error string Empty on success.
campaign_id string Campaign id.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.
Invalid or missing action 400 action is absent or not a supported action.
Cannot edit campaign - not in draft status 400 The campaign is not in DRAFT.
Invalid campaign type 400 type is not sms, email, or both.
Unicode requires the UTF16 feature on your account 400 sms_unicode_enabled set without the UTF16 account feature.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""action"": ""update"",
    ""title"": ""July promo (final)"",
    ""sms_body"": ""Hello from Acme! Reply STOP to opt out.""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "message": "Campaign updated"
}
{
  "error": "Cannot edit campaign - not in draft status"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Add recipients

POST https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Add recipients to a draft campaign — individual numbers, individual emails, and/or whole contact lists. Only campaigns in DRAFT status accept recipients. Individual numbers and emails are capped at 100 combined per call; contact lists have no per-call cap. Duplicates and invalid entries are skipped and reported in errors while the rest are added (the top-level error stays empty).

Request body parameters

Field Type Required Description
action string Yes Must be add_recipients.
numbers string or array No Phone numbers. Array, or comma/newline-delimited string.
emails string or array No Email addresses. Same format as numbers.
contact_list_ids string or array No Contact list ids (24-char hex) you own.

At least one of numbers, emails, or contact_list_ids must be non-empty.

Response fields

Field Type Description
error string Empty on success.
added integer Individual recipients successfully added.
errors array Per-item messages for skipped entries — e.g. Number already added: ..., Invalid email address: ..., Invalid contact list id: ..., or Maximum 100 individual recipients per call.
recipient_count integer Total recipients on the campaign after the call.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.
Invalid or missing action 400 action is absent or not a supported action.
Cannot modify recipients - not in draft status 400 The campaign is not in DRAFT.
No recipients provided 400 None of numbers/emails/contact_list_ids supplied.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""action"": ""add_recipients"",
    ""numbers"": [
        ""0404123123"",
        ""0404123124""
    ],
    ""contact_list_ids"": [
        ""683554c596937cc4b90f5cf7""
    ]
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "added": 2,
  "errors": [],
  "recipient_count": 242
}
{
  "error": "No recipients provided"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Remove recipient

POST https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Remove a single recipient row (an individual, or a whole contact-list source) from a draft campaign. Use the recipient id from Get campaign's recipients array. Only campaigns in DRAFT status can be modified.

Request body parameters

Field Type Required Description
action string Yes Must be remove_recipient.
recipient_id string Yes The recipient row id (24-char hex).

Response fields

Field Type Description
error string Empty on success.
recipient_count integer Total recipients remaining.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.
Invalid or missing action 400 action is absent or not a supported action.
Cannot modify recipients - not in draft status 400 The campaign is not in DRAFT.
recipient_id is required 400 recipient_id missing or not a valid id.
Recipient not found 400 No such recipient row on this campaign.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""action"": ""remove_recipient"",
    ""recipient_id"": ""665f1a2b3c4d5e6f7a8b9c11""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "recipient_count": 2
}
{
  "error": "recipient_id is required"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Clear recipients

POST https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Remove all recipients from a draft campaign. Only campaigns in DRAFT status can be modified.

Request body parameters

Field Type Required Description
action string Yes Must be clear_recipients.

Response fields

Field Type Description
error string Empty on success.
recipient_count integer Always 0 on success.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.
Invalid or missing action 400 action is absent or not a supported action.
Cannot modify recipients - not in draft status 400 The campaign is not in DRAFT.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "clear_recipients"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "clear_recipients"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "clear_recipients"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "clear_recipients"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "clear_recipients"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""action"": ""clear_recipients""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "clear_recipients"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "clear_recipients"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "recipient_count": 0
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Send / schedule campaign

POST https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Send a draft campaign now, or schedule it for a future time. The campaign must be in DRAFT and pass all readiness and account-gating checks. Omit schedule to send immediately; supply it to schedule.

Send-time gating enforces, per channel: an active email plan and a verified sending domain (email), and SMS credits or a postpaid account (SMS). Unified Virtual Number senders are capped at 100 recipients; a coupon may only be attached to a Unified Virtual Number sender.

Request body parameters

Field Type Required Description
action string Yes Must be send.
schedule integer or string No Unix timestamp or a strtotime-parseable string, in the future. Omit to send immediately.

Response fields

Field Type Description
error string Empty on success.
campaign_id string Campaign id.
status string SENDING (immediate) or SCHEDULED.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.
Invalid or missing action 400 action is absent or not a supported action.
Campaign is not in draft status 400 The campaign is not in DRAFT.
You need an active email plan to send email campaigns 400 Email campaign with no email quota.
You need a verified domain to send email campaigns 400 Email campaign with no verified sending domain.
You need SMS credits or a postpaid account to send SMS campaigns 400 SMS campaign with zero balance and not postpaid.
Unified campaigns are limited to 100 recipients. 400 Unified Virtual Number sender with more than 100 recipients.
A coupon can only be attached when the Sender ID is a Unified Virtual Number. Remove the coupon or choose a unified sender. 400 Coupon attached with a non-unified, non-blue sender.
Scheduled time must be in the future 400 schedule did not parse or is not in the future.
No recipients added 400 Readiness: campaign has no recipients.
SMS sender ID is required 400 Readiness: SMS channel missing sender ID.
SMS message body is required 400 Readiness: SMS channel missing body.
SMS message is too long (max 760 characters) 400 Readiness: SMS body exceeds the GSM length limit.
Unicode SMS message is too long (max 335 characters) 400 Readiness: unicode SMS body exceeds the unicode length limit.
Sender email is required 400 Readiness: email channel missing sender email.
Sender name is required 400 Readiness: email channel missing sender name.
Subject line is required 400 Readiness: email channel missing subject.
Email body is required 400 Readiness: email channel missing body.
Campaign is already sending 400 Send already in progress.
Campaign is already scheduled 400 A schedule is already set.
Campaign has already been sent 400 The campaign was already sent.
Failed to start campaign 400 The send could not be started (defensive fallback).

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "send"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "send"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "send"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "send"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "send"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""action"": ""send""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "send"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "send"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "status": "SENDING",
  "message": "Campaign started"
}
{
  "error": "You need a verified domain to send email campaigns"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Cancel schedule

POST https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Cancel a scheduled campaign and return it to DRAFT. Only works while the campaign is SCHEDULED and more than 30 minutes remain before the scheduled send.

Request body parameters

Field Type Required Description
action string Yes Must be cancel_schedule.

Response fields

Field Type Description
error string Empty on success.
campaign_id string Campaign id.
status string DRAFT.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.
Invalid or missing action 400 action is absent or not a supported action.
Campaign is not scheduled 400 The campaign is not in SCHEDULED.
Cannot cancel - less than 30 minutes until scheduled send 400 Too close to the scheduled send time.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "cancel_schedule"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "cancel_schedule"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "cancel_schedule"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "cancel_schedule"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "cancel_schedule"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""action"": ""cancel_schedule""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "cancel_schedule"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "action": "cancel_schedule"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "status": "DRAFT",
  "message": "Schedule cancelled"
}
{
  "error": "Cannot cancel - less than 30 minutes until scheduled send"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete campaign

DELETE https://www.5centsms.com.au/api/v5/campaigns/:id

Include key-id and key-secret in the JSON body of every request.

Delete a campaign and its recipients. Only draft campaigns can be deleted — campaigns that are sending, scheduled, or already sent cannot be removed.

Response fields

Field Type Description
error string Empty on success.
campaign_id string The deleted campaign's id.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid campaign_id format 400 The path id is not a 24-char hex id.
Campaign not found 400 No such campaign on this account.
Cannot delete campaign 400 The campaign is sending, scheduled, or sent.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/campaigns/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/campaigns/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/campaigns/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "message": "Campaign deleted"
}
{
  "error": "Cannot delete campaign"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Sender IDs

GET https://www.5centsms.com.au/api/v5/senderid

Include key-id and key-secret in the JSON body of every request.

List the sender IDs registered on your account.

Response fields

Field Type Description
error string Empty on success.
senderids array Registered sender IDs.
senderids[].id string Sender ID record id.
senderids[].senderid string The sender ID value.
senderids[].status string Approval status.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/senderid \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/senderid"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/senderid", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/senderid");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/senderid"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/senderid");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/senderid", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/senderid")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "senderids": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "senderid": "EXAMPLE",
      "status": "approved"
    }
  ]
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Sender ID

POST https://www.5centsms.com.au/api/v5/senderid

Include key-id and key-secret in the JSON body of every request.

Register a new sender ID for approval.

Request body parameters

Field Type Required Description
senderid string Yes The sender ID to register.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.

Errors

Error HTTP Cause
Missing Sender ID 400 senderid not supplied.
Invalid new Sender ID 400 senderid is not valid.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/senderid \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "senderid": "EXAMPLE"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/senderid"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "senderid": "EXAMPLE"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "senderid": "EXAMPLE"
});

const req = https.request("https://www.5centsms.com.au/api/v5/senderid", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/senderid");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "senderid": "EXAMPLE"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "senderid": "EXAMPLE"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/senderid"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/senderid");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""senderid"": ""EXAMPLE""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "senderid": "EXAMPLE"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/senderid", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/senderid")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "senderid": "EXAMPLE"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Sender ID created"
}
{
  "error": "Invalid new Sender ID"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Sender ID

DELETE https://www.5centsms.com.au/api/v5/senderid/:id

Include key-id and key-secret in the JSON body of every request.

Remove a sender ID from your account.

Response fields

Field Type Description
error string Empty on success.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idSender ID record id.
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/senderid/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/senderid/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/senderid/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/senderid/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/senderid/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/senderid/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/senderid/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/senderid/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": ""
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Virtual Numbers

GET https://www.5centsms.com.au/api/v5/virtualnumber

Include key-id and key-secret in the JSON body of every request.

List the virtual numbers on your account.

Response fields

Field Type Description
error string Empty on success.
virtualnumbers array Virtual numbers.
virtualnumbers[].id string Virtual number record id.
virtualnumbers[].number string Number in international format.
virtualnumbers[].number_formatted string Human-formatted number.
virtualnumbers[].country string Country code.
virtualnumbers[].type string standard or unified.
count integer Number of virtual numbers.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/virtualnumber \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/virtualnumber"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/virtualnumber", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/virtualnumber");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/virtualnumber"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/virtualnumber");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/virtualnumber", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/virtualnumber")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "virtualnumbers": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "number": "61400000000",
      "number_formatted": "0400 000 000",
      "country": "AU",
      "type": "standard"
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Purchase Virtual Number

POST https://www.5centsms.com.au/api/v5/virtualnumber

Include key-id and key-secret in the JSON body of every request.

Purchase a virtual number. Charges the card on file and creates a monthly subscription. Default limit 2 numbers unless the MORE_VMNS flag is set.

Request body parameters

Field Type Required Description
country string Yes Only AU is supported for API purchases.
type string No standard or unified. Default standard; unified requires the ENABLE_UNIFIED flag.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.
virtualnumber object {id, number, number_formatted, country}.

Errors

Error HTTP Cause
Missing required parameter: country 400 country not supplied.
Invalid country. Currently only AU is supported for API requests. 400 country is not AU.
Invalid type. Must be "standard" or "unified". 400 type is not an allowed value.
Your account is not enabled for Unified Mobile Numbers. Please contact us. 400 type: unified without the ENABLE_UNIFIED flag.
Your account is currently on hold. Please contact us to purchase a virtual number. 400 Account is on hold.
Maximum virtual numbers reached. Contact us to request increaed quota. 400 Number limit reached (default 2).
No payment method on file. Please add a payment method in the dashboard. 400 No card on file.
Invalid subscription plan 400 Subscription plan could not be resolved.
Your payment was declined by your bank. 400 Card charge declined.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/virtualnumber \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "country": "AU",
    "type": "standard"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/virtualnumber"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "country": "AU",
    "type": "standard"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "country": "AU",
    "type": "standard"
});

const req = https.request("https://www.5centsms.com.au/api/v5/virtualnumber", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/virtualnumber");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "country": "AU",
    "type": "standard"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "country": "AU",
    "type": "standard"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/virtualnumber"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/virtualnumber");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""country"": ""AU"",
    ""type"": ""standard""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "country": "AU",
    "type": "standard"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/virtualnumber", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/virtualnumber")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "country": "AU",
    "type": "standard"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Virtual number purchased",
  "virtualnumber": {
    "id": "683554c596937cc4b90f5cf7",
    "number": "61400000000",
    "number_formatted": "0400 000 000",
    "country": "AU"
  }
}
{
  "error": "Invalid country. Currently only AU is supported for API requests."
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Virtual Number

DELETE https://www.5centsms.com.au/api/v5/virtualnumber/:id

Include key-id and key-secret in the JSON body of every request.

Release a virtual number and cancel its subscription.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid virtual number ID format 400 id is not a valid id.
Virtual number not found 400 No such virtual number.
Unauthorized - you do not own this virtual number 400 Number not owned by this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idVirtual number record id.
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/virtualnumber/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/virtualnumber/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/virtualnumber/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/virtualnumber/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/virtualnumber/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/virtualnumber/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/virtualnumber/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/virtualnumber/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Virtual number released"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Domains

GET https://api.dingomail.com.au/api/v5/domain

Include key-id and key-secret in the JSON body of every request.

List the email domains registered on your account.

Response fields

Field Type Description
error string Empty on success.
domains array Registered domains.
domains[].id string Domain record id.
domains[].domain string Domain name.
domains[].subdomain string Sending subdomain.
domains[].status string Verification status.
domains[].dkim_names array DKIM record names.
domains[].verification string SES verification state.
count integer Number of domains.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/domain \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/domain"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://api.dingomail.com.au/api/v5/domain", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/domain");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/domain"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.dingomail.com.au/api/v5/domain");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/domain", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/domain")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "domains": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "domain": "example.com",
      "subdomain": "email",
      "status": "verified",
      "dkim_names": [
        "k1._domainkey"
      ],
      "verification": "verified"
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Domain

GET https://api.dingomail.com.au/api/v5/domain/:id

Include key-id and key-secret in the JSON body of every request.

Fetch a single email domain, including its DKIM and verification details.

Response fields

Field Type Description
error string Empty on success.
domain object id, domain, subdomain, status, dkim_names, verification.

Errors

Error HTTP Cause
Failed (Domain not found or unauthorized) 400 No such domain, or not owned by this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idDomain record id.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/domain/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/domain/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://api.dingomail.com.au/api/v5/domain/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/domain/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/domain/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.dingomail.com.au/api/v5/domain/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/domain/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/domain/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "domain": {
    "id": "683554c596937cc4b90f5cf7",
    "domain": "example.com",
    "subdomain": "email",
    "status": "verified",
    "dkim_names": [
      "k1._domainkey"
    ],
    "verification": "verified"
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Domain

POST https://api.dingomail.com.au/api/v5/domain

Include key-id and key-secret in the JSON body of every request.

Register a new email domain. Email must be enabled and your plan's domain limit must not be exceeded.

Request body parameters

Field Type Required Description
domain string Yes Domain name (valid domain format).
subdomain string No Sending subdomain; letters, numbers, hyphens. Default email. If a full host is supplied it is auto-corrected and a warning is returned.

Response fields

Field Type Description
error string Empty on success.
message object {id, domain}.
warning string Present only when the subdomain was auto-corrected.

Errors

Error HTTP Cause
Email not enabled. Please contact us. 400 Email is not enabled on this account.
Domain limit reached. Your plan allows {n} domain{s}. Please upgrade your plan or contact us. 400 Plan domain limit reached.
Missing Domain 400 domain not supplied.
Invalid Domain 400 domain is not a valid domain.
Domain already registered. Please contact us. 400 Domain already exists.
Invalid subdomain. Use only letters, numbers, and hyphens. 400 subdomain contains invalid characters.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/domain \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "domain": "example.com",
    "subdomain": "email"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/domain"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "domain": "example.com",
    "subdomain": "email"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "domain": "example.com",
    "subdomain": "email"
});

const req = https.request("https://api.dingomail.com.au/api/v5/domain", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/domain");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "domain": "example.com",
    "subdomain": "email"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "domain": "example.com",
    "subdomain": "email"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/domain"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.dingomail.com.au/api/v5/domain");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""domain"": ""example.com"",
    ""subdomain"": ""email""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "domain": "example.com",
    "subdomain": "email"
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/domain", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/domain")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "domain": "example.com",
    "subdomain": "email"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": {
    "id": "683554c596937cc4b90f5cf7",
    "domain": "example.com"
  }
}
{
  "error": "Invalid Domain"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Mailboxes

GET https://api.dingomail.com.au/api/v5/mailboxes

Include key-id and key-secret in the JSON body of every request.

List the hosted mailboxes on your account, active and inactive.

Response fields

Field Type Description
mailboxes array One object per mailbox.
mailboxes[].id string Mailbox id (use with Enable / Disable Mailbox).
mailboxes[].address string Full mailbox address.
mailboxes[].active boolean false when the mailbox is disabled — inbound to it is dropped and it cannot send.
mailboxes[].created integer Unix timestamp the mailbox was created, or null.
count integer Number of mailboxes returned.
error string Empty on success.

Errors

No endpoint-specific errors — authentication errors per the intro's 401 table.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/mailboxes \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/mailboxes"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://api.dingomail.com.au/api/v5/mailboxes", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/mailboxes");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/mailboxes"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.dingomail.com.au/api/v5/mailboxes");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/mailboxes", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/mailboxes")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "count": 2,
  "mailboxes": [
    {
      "id": "66a1f2c3d4e5f6a7b8c9d0e1",
      "address": "newsletter@mydingo.au",
      "active": true,
      "created": 1753142400
    },
    {
      "id": "66a1f2c3d4e5f6a7b8c9d0e2",
      "address": "old@mydingo.au",
      "active": false,
      "created": 1750464000
    }
  ]
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Mailbox

POST https://api.dingomail.com.au/api/v5/mailboxes

Include key-id and key-secret in the JSON body of every request.

Create a hosted mailbox. The new mailbox is active immediately and can send and receive at <name>@mydingo.au. Creation counts against your plan's mailbox quota (active mailboxes only).

Request body

Field Type Required Description
name string yes The local part (the text before the @). Lowercased. Letters, numbers and . _ - only, must start and end with a letter or number, maximum 64 characters. + is not allowed. Reserved names (role addresses such as postmaster, abuse, admin, and brand terms) are rejected. Must be globally unique across all accounts.

Response fields

Field Type Description
mailbox.id string The new mailbox id.
mailbox.address string The full mailbox address.
mailbox.active boolean Always true on create.
mailbox.created integer Unix timestamp.
message string Mailbox created.
error string Empty on success.

Errors

Error HTTP Cause
Mailboxes are not included in your plan 400 The account's mailbox quota is 0.
Unable to create mailboxes at this time. Please contact us. 400 Please contact us
Mailbox limit reached 400 The account already has as many active mailboxes as its quota allows.
Name Required. Please see our API Docs 400 name missing or empty.
Mailbox name may only contain letters, numbers, and . _ - characters. 400 name fails the format rule.
Mailbox name must be 64 characters or fewer. 400 name longer than 64 characters.
That mailbox name is reserved. Please choose another name. 400 name is on the reserved list.
That mailbox is already taken. Please choose another name. 400 The address exists on any account (including disabled mailboxes).

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/mailboxes \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "newsletter"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/mailboxes"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "newsletter"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "newsletter"
});

const req = https.request("https://api.dingomail.com.au/api/v5/mailboxes", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/mailboxes");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "newsletter"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "newsletter"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/mailboxes"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.dingomail.com.au/api/v5/mailboxes");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""name"": ""newsletter""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "newsletter"
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/mailboxes", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/mailboxes")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "newsletter"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Mailbox created",
  "mailbox": {
    "id": "66a1f2c3d4e5f6a7b8c9d0e1",
    "address": "newsletter@mydingo.au",
    "active": true,
    "created": 1753142400
  }
}
{
  "error": "That mailbox is already taken. Please choose another name."
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Enable / Disable Mailbox

POST https://api.dingomail.com.au/api/v5/mailboxes/:id

Include key-id and key-secret in the JSON body of every request.

Enable or disable a hosted mailbox. A disabled mailbox drops inbound email, cannot be used as a sender address, and does not count toward the mailbox quota — but keeps its address reserved to your account. Re-enabling is blocked while the account is already at its active-mailbox quota. There is no delete: mailboxes are removed only when the account closes.

Request body

Field Type Required Description
active boolean yes true to enable, false to disable.

Response fields

Field Type Description
mailbox object The updated mailbox (id, address, active, created).
message string Mailbox updated.
error string Empty on success.

Errors

Error HTTP Cause
Invalid Mailbox ID 400 The path id is not a 24-character hex id.
Mailbox Not Found 400 No mailbox with that id on this account.
active Required. Please see our API Docs 400 active missing or not a boolean.
Mailbox limit reached 400 Enabling would exceed the account's active-mailbox quota.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idMailbox id (from List Mailboxes).
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/mailboxes/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "active": false
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/mailboxes/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "active": false
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "active": false
});

const req = https.request("https://api.dingomail.com.au/api/v5/mailboxes/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/mailboxes/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "active": false
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "active": false
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/mailboxes/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://api.dingomail.com.au/api/v5/mailboxes/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""active"": false
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "active": false
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/mailboxes/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://api.dingomail.com.au/api/v5/mailboxes/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "active": false
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Mailbox updated",
  "mailbox": {
    "id": "66a1f2c3d4e5f6a7b8c9d0e1",
    "address": "newsletter@mydingo.au",
    "active": false,
    "created": 1753142400
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Contact List

POST https://www.5centsms.com.au/api/v5/lists

Include key-id and key-secret in the JSON body of every request.

Create a contact list.

Request body parameters

Field Type Required Description
name string Yes List name.

Response fields

Field Type Description
error string Empty on success.
list.id string New list id.
list.name string List name.
list.status string active on creation.
list.count integer Contact count (0 for a new list).
message string Confirmation message.

Errors

Error HTTP Cause
Missing required field: name 400 name not supplied or empty.
List update is not supported 400 POSTing to a list id (/lists/{id}) — renaming or changing a list's status is not available via the API; manage it in the dashboard.

Notes

  • Lists are create-and-delete only through the API. There is no rename or archive endpoint.
  • Deleting a list also deletes every contact in it (see Delete List).

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/lists \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "VIP Customers"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/lists"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "VIP Customers"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "VIP Customers"
});

const req = https.request("https://www.5centsms.com.au/api/v5/lists", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/lists");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "VIP Customers"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "VIP Customers"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/lists");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""name"": ""VIP Customers""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "VIP Customers"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/lists", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/lists")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "name": "VIP Customers"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "list": {
    "id": "683554c596937cc4b90f5cf7",
    "name": "VIP Customers",
    "status": "active",
    "count": 0
  },
  "message": "List created"
}
{
  "error": "Missing required field: name"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Contact Lists

GET https://www.5centsms.com.au/api/v5/lists

Include key-id and key-secret in the JSON body of every request.

List all contact lists on your account, each with its current contact count.

Response fields

Field Type Description
error string Empty on success.
lists array Contact lists.
lists[].id string List id.
lists[].name string List name.
lists[].status string active or archived.
lists[].count integer Number of contacts in the list.
count integer Number of lists.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/lists \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/lists"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/lists", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/lists");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/lists");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/lists", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/lists")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "lists": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "name": "VIP Customers",
      "status": "active",
      "count": 128
    }
  ],
  "count": 1
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Contact List

GET https://www.5centsms.com.au/api/v5/lists/:id

Include key-id and key-secret in the JSON body of every request.

Get a single contact list by id.

Response fields

Field Type Description
error string Empty on success.
list.id string List id.
list.name string List name.
list.status string active or archived.
list.count integer Number of contacts in the list.

Errors

Error HTTP Cause
Invalid list ID format 400 The id is not a 24-hex value.
List not found 400 No such list on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idContact list id (24-hex).
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/lists/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/lists/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/lists/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/lists/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/lists/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/lists/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/lists/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "list": {
    "id": "683554c596937cc4b90f5cf7",
    "name": "VIP Customers",
    "status": "active",
    "count": 128
  }
}
{
  "error": "List not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Contact List

DELETE https://www.5centsms.com.au/api/v5/lists/:id

Include key-id and key-secret in the JSON body of every request.

Delete a contact list and every contact in it. This cannot be undone.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid list ID format 400 The id is not a 24-hex value.
List not found 400 No such list on this account.

Notes

  • The delete cascades: every contact whose list_id is this list is removed along with the list.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idContact list id (24-hex).
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/lists/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/lists/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/lists/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/lists/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/lists/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/lists/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/lists/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "List and its contacts deleted"
}
{
  "error": "List not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Contact

POST https://www.5centsms.com.au/api/v5/contacts

Include key-id and key-secret in the JSON body of every request.

Create one contact, or many in a single call.

  • Single: send the contact fields at the top level.
  • Batch: send a contacts array. Every row is inserted into the one list_id, and the response reports per-row results. Batch is best-effort — a row that isn't a JSON object is skipped and reported in results[]; the rest still insert. Max 1000 rows per call.

Request body parameters

Field Type Required Description
list_id string Yes Target list id; must belong to your account.
number string No Phone number; normalised to 614… format on save.
first_name string No Contact's first name.
last_name string No Contact's last name.
email string No Contact's email address.
meta object No Custom fields — arbitrary key/value pairs. Scalar values only (array/object values are dropped); . and $ in keys are replaced with _.
contacts array No Batch mode: array of contact objects, each carrying the fields above except list_id. Presence of this field switches to batch mode.

Response fields (single)

Field Type Description
error string Empty on success.
contact object The created contact: id, list_id, number, first_name, last_name, email, meta.
message string Confirmation message.

Response fields (batch)

Field Type Description
error string Empty — a batch always returns HTTP 200; per-row failures are in results.
created integer Rows inserted.
failed integer Rows skipped.
results array Per row: {index, id} on success or {index, error} on failure.
message string Batch processed.

Errors

Error HTTP Cause
Missing required field: list_id 400 list_id not supplied.
Invalid list ID format 400 list_id not a 24-hex value.
List not found 400 The list doesn't exist or isn't yours.
contacts must be a non-empty array 400 Batch mode with an empty or non-array contacts.
Batch too large. Maximum 1000 contacts per request 400 Batch contacts has more than 1000 rows.
Invalid contact object (per-row) A contacts[] row is not an object — reported in results[].error, not at the top level (HTTP stays 200).

Notes

  • Custom fields have no per-account schema; any key you send under meta is stored as-is.
  • Create is not deduplicated — re-sending the same contact creates a duplicate.
  • A batch targets a single list; mixing lists in one call is not supported.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "0412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
        "company": "Acme",
        "plan": "gold"
    }
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "0412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
        "company": "Acme",
        "plan": "gold"
    }
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "0412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
        "company": "Acme",
        "plan": "gold"
    }
});

const req = https.request("https://www.5centsms.com.au/api/v5/contacts", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/contacts");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "0412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
        "company": "Acme",
        "plan": "gold"
    }
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "0412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
        "company": "Acme",
        "plan": "gold"
    }
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/contacts");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""list_id"": ""683554c596937cc4b90f5cf7"",
    ""number"": ""0412333555"",
    ""first_name"": ""Jane"",
    ""last_name"": ""Smith"",
    ""email"": ""jane@example.com"",
    ""meta"": {
        ""company"": ""Acme"",
        ""plan"": ""gold""
    }
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "0412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
        "company": "Acme",
        "plan": "gold"
    }
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/contacts", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/contacts")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "0412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
        "company": "Acme",
        "plan": "gold"
    }
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "contact": {
    "id": "683554c596937cc4b90f5cf8",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "61412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
      "company": "Acme",
      "plan": "gold"
    }
  },
  "message": "Contact created"
}
{
  "error": "",
  "created": 2,
  "failed": 1,
  "results": [
    { "index": 0, "id": "683554c596937cc4b90f5cf8" },
    { "index": 1, "id": "683554c596937cc4b90f5cf9" },
    { "index": 2, "error": "Invalid contact object" }
  ],
  "message": "Batch processed"
}
{
  "error": "Missing required field: list_id"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Contacts

GET https://www.5centsms.com.au/api/v5/contacts

Include key-id and key-secret in the JSON body of every request.

List contacts, newest first, or search them.

  • Without search: a keyset-paginated list, optionally filtered by list_id.
  • With search: a substring match over name / number / email, also keyset-paginated.

Response fields

Field Type Description
error string Empty on success.
contacts array Contacts on this page.
contacts[].id string Contact id.
contacts[].list_id string Owning list id.
contacts[].number string Phone number (614… format).
contacts[].first_name string First name.
contacts[].last_name string Last name.
contacts[].email string Email address.
contacts[].meta object Custom fields (empty object when none).
count integer Contacts on this page.
next_page string Relative path for the next page; empty when there are no further results.

Errors

Error HTTP Cause
Invalid list ID format 400 list_id is not a 24-hex value.
Failed (Invalid Page) 400 after is not a valid 24-hex cursor.

Notes

  • Plain-list page size defaults to 100 (limit 1–1000). Search page size defaults to 500 (limit 1–500).
  • next_page is present only when a full page was returned; follow it until it is empty. The paging examples below use limit=2 to stay short.
  • Search is inherently a substring scan — for a rare term over a very large contact book a page may take longer to fill.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
list_idOptional. Restrict to one list (24-hex).
searchOptional. Case-insensitive substring match on first name, last name, number, or email.
after24-hex cursor — the `id` of the last contact on the previous page.
limitPage size. Plain list: 1–1000 (default 100). Search: 1–500 (default 500).
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/contacts", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/contacts");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/contacts");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/contacts", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/contacts")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "contacts": [
    {
      "id": "683554c596937cc4b90f5cf8",
      "list_id": "683554c596937cc4b90f5cf7",
      "number": "61412333555",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "meta": {
        "company": "Acme"
      }
    },
    {
      "id": "683554c596937cc4b90f5cf6",
      "list_id": "683554c596937cc4b90f5cf7",
      "number": "61412333777",
      "first_name": "Tom",
      "last_name": "Jones",
      "email": "tom@example.com",
      "meta": {}
    }
  ],
  "count": 2,
  "next_page": "/api/v5/contacts?after=683554c596937cc4b90f5cf6"
}
{
  "error": "",
  "contacts": [
    {
      "id": "683554c596937cc4b90f5cf4",
      "list_id": "683554c596937cc4b90f5cf7",
      "number": "61412333999",
      "first_name": "Amy",
      "last_name": "Lee",
      "email": "amy@example.com",
      "meta": {}
    }
  ],
  "count": 1,
  "next_page": ""
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Contact

GET https://www.5centsms.com.au/api/v5/contacts/:id

Include key-id and key-secret in the JSON body of every request.

Get a single contact by id.

Response fields

Field Type Description
error string Empty on success.
contact object The contact: id, list_id, number, first_name, last_name, email, meta.

Errors

Error HTTP Cause
Invalid contact ID format 400 The id is not a 24-hex value.
Contact not found 400 No such contact on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idContact id (24-hex).
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/contacts/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/contacts/:id", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/contacts/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts/:id"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/contacts/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/contacts/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/contacts/:id")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "contact": {
    "id": "683554c596937cc4b90f5cf8",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "61412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "meta": {
      "company": "Acme"
    }
  }
}
{
  "error": "Contact not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Update Contact

POST https://www.5centsms.com.au/api/v5/contacts/:id

Include key-id and key-secret in the JSON body of every request.

Update fields on a contact. Only the fields you send change.

Request body parameters

Field Type Required Description
number string No Phone number; normalised to 614… on save.
first_name string No First name.
last_name string No Last name.
email string No Email address.
meta object No Custom fields. Replaces the entire meta object — send the full desired set, not a partial patch.

Response fields

Field Type Description
error string Empty on success.
contact object The updated contact.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid contact ID format 400 The id is not a 24-hex value.
Contact not found 400 No such contact on this account.
Nothing to update 400 No recognised field supplied.

Notes

  • meta is replaced wholesale, not merged; omit it to leave custom fields untouched.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idContact id (24-hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/contacts/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "email": "jane.smith@example.com"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "email": "jane.smith@example.com"
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "email": "jane.smith@example.com"
});

const req = https.request("https://www.5centsms.com.au/api/v5/contacts/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/contacts/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "email": "jane.smith@example.com"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "email": "jane.smith@example.com"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/contacts/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""email"": ""jane.smith@example.com""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "email": "jane.smith@example.com"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/contacts/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/contacts/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "email": "jane.smith@example.com"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "contact": {
    "id": "683554c596937cc4b90f5cf8",
    "list_id": "683554c596937cc4b90f5cf7",
    "number": "61412333555",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "meta": {
      "company": "Acme"
    }
  },
  "message": "Contact updated"
}
{
  "error": "Nothing to update"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Contact

DELETE https://www.5centsms.com.au/api/v5/contacts/:id

Include key-id and key-secret in the JSON body of every request.

Delete a contact.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid contact ID format 400 The id is not a 24-hex value.
Contact not found 400 No such contact on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idContact id (24-hex).
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/contacts/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/contacts/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/contacts/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/contacts/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/contacts/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/contacts/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Contact deleted"
}
{
  "error": "Contact not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Webhooks

GET https://www.5centsms.com.au/api/v5/webhooks

Include key-id and key-secret in the JSON body of every request.

List every outbound webhook configuration on your account, including disabled and temporarily-suppressed ones (this is a management view). Optionally filter by type.

Query parameters

Field Type Required Description
type string No Restrict to one type. One of sms_events, sms_inbound, sms_optout, email_inbound, email_events, account_balance.

Response fields

Field Type Description
error string Empty on success.
webhooks array Webhook configurations on the account.
webhooks[].id string Webhook id (24-hex).
webhooks[].type string One of sms_events, sms_inbound, sms_optout, email_inbound, email_events, account_balance.
webhooks[].url string Destination URL the payload is POSTed to.
webhooks[].version integer Payload format version. Currently always 1 (form-encoded); v2/JSON creation is disabled.
webhooks[].threshold integer|null Balance threshold; set only for account_balance webhooks, otherwise null.
webhooks[].events array Subscribed events; populated only for email_events webhooks (subset of delivery, engagement, unsubscribe), otherwise [].
webhooks[].enabled boolean Whether the webhook is currently enabled.
count integer Number of webhooks returned.

Errors

Error HTTP Cause
Invalid type. Must be one of: sms_events, sms_inbound, sms_optout, email_inbound, email_events, account_balance 400 type filter is not an allowed value.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
typeOptional. Restrict to one type: `sms_events`, `sms_inbound`, `sms_optout`, `email_inbound`, `email_events`, `account_balance`.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/webhooks"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("GET", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/webhooks", {
  method: "GET",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/webhooks");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/webhooks"))
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.5centsms.com.au/api/v5/webhooks");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/webhooks", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/webhooks")
request = Net::HTTP::Get.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "webhooks": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "type": "sms_events",
      "url": "https://example.com/dlr",
      "version": 1,
      "threshold": null,
      "events": [],
      "enabled": true
    },
    {
      "id": "7a1b2c3d4e5f60718293a4b5",
      "type": "email_events",
      "url": "https://example.com/email-events",
      "version": 1,
      "threshold": null,
      "events": [
        "delivery",
        "engagement"
      ],
      "enabled": true
    }
  ],
  "count": 2
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Webhook

POST https://www.5centsms.com.au/api/v5/webhooks

Include key-id and key-secret in the JSON body of every request.

Create an outbound webhook configuration. The type determines which platform event fires it. Duplicate configurations of the same type are allowed.

Request body parameters

Field Type Required Description
type string Yes One of sms_events, sms_inbound, sms_optout, email_inbound, email_events, account_balance.
url string Yes Destination URL. http:// is prepended if no scheme is given. Loopback and the cloud metadata address are rejected.
threshold integer Conditional Required for type=account_balance: fires when the account balance is at or below this value (must be > 0). Ignored for other types.
events array Conditional Required for type=email_events: a non-empty subset of delivery, engagement, unsubscribe. Duplicates are collapsed. Ignored for other types.

Webhooks are created as v1 (form-encoded payloads); v2/JSON creation is currently disabled.

Response fields

Field Type Description
error string Empty on success.
webhook object The created webhook (id, type, url, version, threshold, events, enabled).
message string Confirmation message.

Errors

Error HTTP Cause
Missing required field: type 400 type not supplied.
Invalid type. Must be one of: sms_events, sms_inbound, sms_optout, email_inbound, email_events, account_balance 400 type is not an allowed value.
Missing required field: url 400 url not supplied.
Balance webhooks require a numeric threshold greater than 0 400 type=account_balance with a missing or non-positive threshold.
Email webhooks require a non-empty events array (subset of: delivery, engagement, unsubscribe) 400 type=email_events with events absent, not an array, or empty.
Invalid event. Must be one of: delivery, engagement, unsubscribe 400 type=email_events with an events value outside the allowlist.
Invalid URL format 400 url fails URL validation.
URL must use http or https protocol 400 url scheme is not http/https.
URL must have a valid domain 400 url has no host.
Invalid URL protocol 400 url contains a file:// protocol.
Cannot use localhost URLs 400 url host is localhost/127.0.0.1/::1.
Invalid URL 400 url targets the cloud metadata address (169.254.169.254).

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/webhooks"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
});

const req = https.request("https://www.5centsms.com.au/api/v5/webhooks", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/webhooks");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/webhooks"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/webhooks");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""type"": ""email_events"",
    ""url"": ""https://example.com/email-events"",
    ""events"": [
        ""delivery"",
        ""engagement""
    ]
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/webhooks", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/webhooks")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "webhook": {
    "id": "7a1b2c3d4e5f60718293a4b5",
    "type": "email_events",
    "url": "https://example.com/email-events",
    "version": 1,
    "threshold": null,
    "events": [
      "delivery",
      "engagement"
    ],
    "enabled": true
  },
  "message": "Webhook created"
}
{
  "error": "Email webhooks require a non-empty events array (subset of: delivery, engagement, unsubscribe)"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Enable / Disable Webhook

POST https://www.5centsms.com.au/api/v5/webhooks/:id

Include key-id and key-secret in the JSON body of every request.

Enable or disable an existing webhook by id. This is the only mutation on an existing webhook; url, type, and events are immutable (delete and recreate to change them).

Path parameters

Field Type Required Description
id string Yes Webhook id (24-hex).

Request body parameters

Field Type Required Description
enabled boolean Yes true to enable, false to disable.

Response fields

Field Type Description
error string Empty on success.
webhook object The updated webhook.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid webhook ID format 400 id is not a valid 24-hex id.
Missing required field: enabled 400 enabled not supplied.
Webhook not found 400 No such webhook on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idWebhook id (24-hex).
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/webhooks/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "enabled": false
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/webhooks/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "enabled": false
}''')
response = requests.request("POST", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "enabled": false
});

const req = https.request("https://www.5centsms.com.au/api/v5/webhooks/:id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/webhooks/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "enabled": false
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "enabled": false
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/webhooks/:id"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.5centsms.com.au/api/v5/webhooks/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}"",
    ""enabled"": false
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "enabled": false
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/webhooks/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/webhooks/:id")
request = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}",
    "enabled": false
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "webhook": {
    "id": "683554c596937cc4b90f5cf7",
    "type": "sms_events",
    "url": "https://example.com/dlr",
    "version": 1,
    "threshold": null,
    "events": [],
    "enabled": false
  },
  "message": "Webhook disabled"
}
{
  "error": "Webhook not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Webhook

DELETE https://www.5centsms.com.au/api/v5/webhooks/:id

Include key-id and key-secret in the JSON body of every request.

Delete a webhook configuration by id.

Path parameters

Field Type Required Description
id string Yes Webhook id (24-hex).

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.

Errors

Error HTTP Cause
Invalid webhook ID format 400 id is not a valid 24-hex id.
Webhook not found 400 No such webhook on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idWebhook id (24-hex).
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/webhooks/:id \
  -H "Content-Type: application/json" \
  -d '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/webhooks/:id"
payload = json.loads('''{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}''')
response = requests.request("DELETE", url, json=payload)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
});

const req = https.request("https://www.5centsms.com.au/api/v5/webhooks/:id", {
  method: "DELETE",
  headers: { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.write(body);
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/webhooks/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = """
{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/webhooks/:id"))
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("DELETE"), "https://www.5centsms.com.au/api/v5/webhooks/:id");
request.Content = new StringContent(@"{
    ""key-id"": ""{{key_id}}"",
    ""key-secret"": ""{{key_secret}}""
}", Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	body := strings.NewReader(`{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}`)
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/webhooks/:id", body)
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}
require "net/http"
require "uri"

uri = URI("https://www.5centsms.com.au/api/v5/webhooks/:id")
request = Net::HTTP::Delete.new(uri, "Content-Type" => "application/json")
request.body = '{
    "key-id": "{{key_id}}",
    "key-secret": "{{key_secret}}"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Webhook deleted"
}
{
  "error": "Failed (Invalid API ID or Key)"
}