5c SMS 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 "Authorization: Bearer Paste Key ID here:Paste Key Secret here" \
  -H "Content-Type: application/json" \
  -d '{
    "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 "Authorization: Bearer Paste Key ID here:Paste Key Secret here" \
  -H "Content-Type: application/json" \
  -d '{
    "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. Set them once as the key_id / key_secret collection variables (under the collection's Variables tab) and they apply to every request here.

Send the pair in the Authorization header as a Bearer token, id and secret joined by a colon. This collection is preconfigured to do this on every request:

curl -X POST https://www.5centsms.com.au/api/v5/sms \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{ "sender": "0404123123", "to": "0412333555", "message": "Hello World" }'

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) The key id/secret pair failed verification.

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, SMS Templates.
  • https://api.dingomail.com.au/api/v5 (Dingo Mail): Email, Email Domains, and Email Templates.

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 Email Templates 20 (override with limit, 1–100)
List SMS Templates 20 (override with limit, 1–100)
List Inbound Messages 50
List Opt-outs 1000
List Campaigns 200 (override with limit, 1–200)
Get Campaign Recipients 100 (override with limit, 1–1000)

A malformed after returns HTTP 400 — Failed (Invalid Page) on the SMS / Inbox / Opt-out endpoints, Invalid after parameter on List Emails, List Email Templates, List SMS Templates, List Campaigns and Get Campaign Recipients (all of which also reject a bad limit with Invalid limit parameter). List Campaigns and Get Campaign Recipients emit next_page only when a full page was returned, so paging stops when it is absent. 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
Authorization: Bearer your-key-id:your-key-secret

POST Send SMS

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

Send Authorization: Bearer <key-id>:<key-secret> on 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. Otherwise sent as GSM-7, which means the text is transliterated before sending and the send fails if any character survives that. See Notes.
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

  • GSM-7 messages are transliterated before they are sent. Smart quotes become plain quotes, dashes become hyphens, an ellipsis becomes three dots, and accented letters outside the GSM alphabet lose their accents, so Álvaro is delivered as Alvaro. The bytes you post are not always the bytes that arrive. Accented letters that are already in the GSM alphabet (é, ü, ø, à, ñ) are left exactly as sent.
  • Any character still outside the GSM alphabet after transliteration is rejected. The request returns 200, but that recipient's messages[].status is 1701 (Failed (Invalid Characters in Message)), nothing is delivered and no credit is charged. This covers emoji, CJK, and symbols with no GSM equivalent such as °, ‰, ✓ and ¢. Set unicode to true to send them as UTF-16 instead, or call POST /segments first to see exactly which characters a body would fail on.
  • 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "sender": "0404123123",
    "to": "0412333555",
    "message": "Hello World",
    "test": false,
    "unicode": false,
    "schedule": 0
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "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: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/sms"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/sms", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/sms"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/sms", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/sms/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/sms/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/sms/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/sms/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/sms/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/sms/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/sms/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/sms/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

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

Query parameters

Field Type Required Description
after string No 24-hex cursor - the id of the last message on the previous page. Returns messages older than that id.
include_archived boolean No Set to 1 to include archived messages. Excluded by default.

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.
messages[].archived boolean True when the account has archived this message. Only ever true when include_archived is set.
next_page string Relative path for the next page. Always present on this endpoint - stop paging when messages is empty (count is 0). It carries include_archived when that flag was set.
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.
  • The list is newest-first and after pages backwards through it: each page returns the 50 messages older than the cursor.
  • Archived messages are excluded from this list. Pass include_archived=1 to include them. Archive with POST /inbox/{id}. Archiving cannot be reversed.
  • Archiving does not delete: an archived message keeps its text, its attachments, and its place in the conversation, and its 356-day retention is unchanged.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
after24-hex cursor - the `id` of the last message on the previous page. Returns messages older than that id, matching this list's newest-first order.
include_archived1Optional. Set to 1 to include archived messages. Archived messages are excluded by default.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/inbox \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/inbox"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/inbox", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/inbox"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/inbox", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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",
      "archived": false
    },
    {
      "id": "683554c596937cc4b90f5cf3",
      "to": "0400000000",
      "from": "0412999888",
      "message": "Yes, please book me in",
      "date": 1716999500,
      "contact_name": "Tom",
      "archived": false
    }
  ],
  "next_page": "/api/v5/inbox?after=683554c596937cc4b90f5cf3",
  "count": 2
}
{
  "error": "",
  "messages": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "to": "0400000000",
      "from": "0412333555",
      "message": "STOP",
      "date": 1717000000,
      "contact_name": "Jane",
      "archived": true
    },
    {
      "id": "683554c596937cc4b90f5cf3",
      "to": "0400000000",
      "from": "0412999888",
      "message": "Yes, please book me in",
      "date": 1716999500,
      "contact_name": "Tom",
      "archived": false
    }
  ],
  "next_page": "/api/v5/inbox?after=683554c596937cc4b90f5cf3&include_archived=1",
  "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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Delete a single inbound message record.

Response fields

Field Type Description
error string Empty on success.

Errors

Error HTTP Cause
Failed (Invalid message ID format) 400 The id path segment is not a 24-character hexadecimal id.
Failed (Unauthorised) 400 Message not found, or not owned by this account.

Notes

  • This permanently removes the message document. To keep the message but hide it from GET /inbox, use POST /inbox/{id} with archived: true instead.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/inbox/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/inbox/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/inbox/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/inbox/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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)"
}

POST Archive Inbound Message

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Archive one received message. Archiving hides the message from GET /inbox unless that call passes include_archived=1; it never deletes the message or its attachments, does not change its 356-day retention, and leaves it visible in the conversation view.

Archiving is permanent. There is no unarchive operation, on this endpoint or in the dashboard. Sending archived: false returns Unarchiving is not supported.

Request body

Field Type Required Description
archived boolean Yes Must be truthy (true, 1, "true"). A falsy value is rejected - archiving cannot be reversed.

Path parameters

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

Response fields

Field Type Description
error string Empty on success.
message string Inbound message archived.
id string The inbound message id acted on.
archived boolean Always true on success.

Errors

Error HTTP Cause
Invalid inbound message ID 400 id is not a valid 24-hex id.
archived Required. Please see our API Docs 400 The body has no archived field.
Unarchiving is not supported 400 archived was sent as false, 0, "false", or null.
Failed (Unauthorised) 400 No such inbound message, or not owned by this account.
Unsupported method. Please see our API Docs 400 POSTed to /inbox with no id.

Notes

  • Idempotent: re-archiving an already-archived message succeeds and returns the same body. It refreshes the stored archive timestamp to the time of the latest request.
  • Archiving is free and does not touch the message balance.
  • To remove the message entirely instead, use DELETE /inbox/{id}.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idInbound message id.
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/inbox/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "archived": true
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/inbox/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "archived": true
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "archived": true
});

const req = https.request("https://www.5centsms.com.au/api/v5/inbox/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "archived": true
}'
]);
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 = """
{
    "archived": true
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/inbox/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/inbox/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""archived"": true
}", 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(`{
    "archived": true
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/inbox/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "archived": true
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Inbound message archived",
  "id": "683554c596937cc4b90f5cf7",
  "archived": true
}
{
  "error": "Unarchiving is not supported"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Opt-outs

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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/optouts"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/optouts", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/optouts"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/optouts", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/optouts/:number"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/optouts/:number", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/optouts/:number"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/optouts/:number", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 (see the intro's Authentication section) 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/statuslist"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/statuslist", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/statuslist"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/statuslist", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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)"
}

POST Calculate SMS Segments

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Measure a message body without sending it. Returns the length we will charge on, how many segments it splits into, the characters we will substitute, and any characters that would cause the send to be rejected. This is the same calculation the send endpoint and the dashboard character counters use, so the segment count returned here is the number of credits a single Australian recipient will cost.

A GSM-7 message is one segment up to 160 characters, and gains a segment at 305, 457 and 609. A Unicode (UCS-2) message is one segment up to 70, and gains a segment at 124, 177 and 230. Five segments is the maximum either way: 765 characters GSM, 335 Unicode.

Some characters count for more than one. The nine GSM 03.38 extension characters (| ^ € { } [ ] ~ \) each occupy two characters in a GSM-7 message, because they are transmitted as an escape byte plus the character; they occupy one in Unicode. Everything else costs one, including accented letters that are in the GSM alphabet (é, ü, ø) and line breaks. message_length is always the figure you will be charged on, so use it rather than counting the string yourself, and note that it is a count of characters as the carrier encodes them, not of bytes: a UTF-8 byte count over-states it.

Before measuring a GSM body we transliterate it: smart quotes become plain quotes, dashes become hyphens, and accented letters outside the GSM alphabet lose their accents. cleaned_message shows the result. Any character still outside the GSM alphabet after that is listed in non_gsm_characters, and a send of the same body would be rejected with status 1701 (Failed - Invalid Characters in Message). Set unicode to true to send those characters as UCS-2 instead.

No message is sent, no credit is charged, and no account state changes.

Request parameters

Field Type Required Description
message string Yes The message body to measure. Maximum 10000 characters.
unicode boolean No Measure as Unicode (UCS-2) instead of GSM-7. No transliteration is applied. Defaults to false.
optout boolean No Include the length of the opt-out link the send path appends. Defaults to false.

Response fields

Field Type Description
error string Empty on success.
message_length integer Chargeable length: characters after transliteration, plus one extra for each GSM extension character, plus optout_length. May be larger than the number of characters you typed.
segments integer Number of segments, 1 to 5. Equals the credits charged per Australian recipient.
encoding string GSM or UCS-2.
extended_characters integer Count of GSM extension characters, ignoring any inside a {{field}} or [#field#] placeholder.
non_gsm_characters array Distinct characters that cannot be sent as GSM-7 even after transliteration. Empty when the body is sendable. Always empty when unicode is true.
cleaned_message string The body as it would be transmitted, after transliteration. Identical to message when unicode is true.
max_length integer Longest body we accept: 765 for GSM, 335 for Unicode, both being five full segments.
characters_remaining integer max_length minus message_length. Negative when the body is over the limit.
optout_length integer Characters added for the opt-out link, or 0 when optout is false.

Errors

Error HTTP Cause
Message text is required 400 message missing, not a string, or empty.
Message text is too long (max 10000 characters) 400 message longer than 10000 characters.
Unsupported method. Please see our API Docs 400 Called with GET 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 POST https://www.5centsms.com.au/api/v5/segments \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Your order {1234} is ready. Café closes at 5pm.",
    "unicode": false,
    "optout": false
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/segments"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "message": "Your order {1234} is ready. Café closes at 5pm.",
    "unicode": false,
    "optout": false
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "message": "Your order {1234} is ready. Café closes at 5pm.",
    "unicode": false,
    "optout": false
});

const req = https.request("https://www.5centsms.com.au/api/v5/segments", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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/segments");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "message": "Your order {1234} is ready. Café closes at 5pm.",
    "unicode": false,
    "optout": 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 = """
{
    "message": "Your order {1234} is ready. Café closes at 5pm.",
    "unicode": false,
    "optout": false
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/segments"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/segments");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""message"": ""Your order {1234} is ready. Café closes at 5pm."",
    ""unicode"": false,
    ""optout"": 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(`{
    "message": "Your order {1234} is ready. Café closes at 5pm.",
    "unicode": false,
    "optout": false
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/segments", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/segments")
request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "message": "Your order {1234} is ready. Café closes at 5pm.",
    "unicode": false,
    "optout": 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_length": 49,
  "segments": 1,
  "encoding": "GSM",
  "extended_characters": 2,
  "non_gsm_characters": [],
  "cleaned_message": "Your order {1234} is ready. Café closes at 5pm.",
  "max_length": 765,
  "characters_remaining": 716,
  "optout_length": 0
}
{
  "error": "",
  "message_length": 14,
  "segments": 1,
  "encoding": "GSM",
  "extended_characters": 0,
  "non_gsm_characters": ["\ud83d\ude00"],
  "cleaned_message": "See you at 5 \ud83d\ude00",
  "max_length": 765,
  "characters_remaining": 751,
  "optout_length": 0
}
{
  "error": "",
  "message_length": 145,
  "segments": 3,
  "encoding": "UCS-2",
  "extended_characters": 0,
  "non_gsm_characters": [],
  "cleaned_message": "...",
  "max_length": 335,
  "characters_remaining": 190,
  "optout_length": 0
}
{
  "error": "Message text is required"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List SMS Templates

GET https://www.5centsms.com.au/api/v5/smstemplates?limit=2

Send Authorization: Bearer <key-id>:<key-secret> on every request.

List the saved SMS templates on your account, newest first. Templates can be created and edited in the dashboard (Templates) or over this API.

Query parameters

Field Type Required Description
limit integer No Rows per page, 1 to 100. Defaults to 20.
after string No Cursor: the id of the last template on the previous page. Returns older templates only.

next_page is present only when a full page was returned, so paginate until it is absent. An account can hold at most 100 SMS templates.

Response fields

Field Type Description
templates array One object per template.
templates[].id string Template id.
templates[].name string Template name.
templates[].text string Message text.
templates[].created integer Unix timestamp the template was created.
count integer Number of templates returned.
next_page string Path to the next page, present only when a full page was returned.
error string Empty on success.

Errors

Error HTTP Cause
Invalid after parameter 400 after is not a 24 character hex id.
Invalid limit parameter 400 limit is not numeric.

Authentication errors are listed in the intro's 401 table.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
limit2Rows per page, 1 to 100. Defaults to 20.
afterCursor: id of the last template on the previous page.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/smstemplates?limit=2 \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/smstemplates?limit=2"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/smstemplates?limit=2"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/smstemplates?limit=2");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/smstemplates?limit=2", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/smstemplates?limit=2")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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,
  "templates": [
    {
      "id": "66c4f0a1b2c3d4e5f6a7b8c9",
      "name": "Appointment reminder",
      "text": "Hi {{FirstName}}, see you at 3pm.",
      "created": 1755648000
    },
    {
      "id": "66b2e1f0a1b2c3d4e5f6a7b8",
      "name": "Payment due",
      "text": "Your invoice is due tomorrow.",
      "created": 1753142400
    }
  ],
  "next_page": "/api/v5/smstemplates?after=66b2e1f0a1b2c3d4e5f6a7b8&limit=2"
}
{
  "error": "",
  "count": 1,
  "templates": [
    {
      "id": "66a0d0e0f1a2b3c4d5e6f7a8",
      "name": "Welcome",
      "text": "Thanks for signing up.",
      "created": 1750464000
    }
  ]
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get SMS Template

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Fetch one SMS template.

Path parameters

Field Type Required Description
id string Yes Template id, 24 hex characters.

Response fields

Field Type Description
template.id string Template id.
template.name string Template name.
template.text string Message text.
template.created integer Unix timestamp the template was created.
error string Empty on success.

Errors

Error HTTP Cause
Invalid template ID 400 The path segment is not a 24 character hex id.
Template not found 400 No template with that id exists on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
id66c4f0a1b2c3d4e5f6a7b8c9Template id, 24 hex characters.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/smstemplates/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/smstemplates/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/smstemplates/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/smstemplates/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/smstemplates/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/smstemplates/:id")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "template": {
    "id": "66c4f0a1b2c3d4e5f6a7b8c9",
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm.",
    "created": 1755648000
  }
}
{
  "error": "Template not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create SMS Template

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Create a saved SMS template. Templates are text you reuse when sending; Send SMS takes the message text directly, so a template is copied into the send by your own code or picked in the dashboard.

When a message goes to a recipient that matches one of your contacts, the send path substitutes {{FirstName}} / {{LastName}} (and the [#Tag#] form) from that contact. Placeholders it cannot resolve are left in the message, so only use them for contact-backed sends.

Request body parameters

Field Type Required Description
name string Yes Template name, 100 characters or less. Names need not be unique.
text string Yes Message text, up to 4096 bytes. Leading and trailing whitespace is trimmed.

Response fields

Field Type Description
template.id string New template id.
template.name string Stored name, trimmed.
template.text string Stored message text, trimmed.
template.created integer Unix timestamp the template was created.
error string Empty on success.

Errors

Error HTTP Cause
Required parameter: name missing 400 name was not sent.
Required parameter: text missing 400 text was not sent.
Field name must be a string 400 name was sent as something other than a string.
Field text must be a string 400 text was sent as something other than a string.
Field text exceeds the 4096 byte limit 400 Message text too large.
Template limit reached (100) 400 The account already holds 100 SMS templates. Delete one first.
Missing name 400 name is empty or whitespace only.
Name must be 100 characters or less 400 Name too long.
Missing text 400 text is empty or whitespace only.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/smstemplates \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm."
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/smstemplates"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm."
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm."
});

const req = https.request("https://www.5centsms.com.au/api/v5/smstemplates", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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/smstemplates");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm."
}'
]);
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 = """
{
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm."
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/smstemplates"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/smstemplates");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""name"": ""Appointment reminder"",
    ""text"": ""Hi {{FirstName}}, see you at 3pm.""
}", 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(`{
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm."
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/smstemplates", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/smstemplates")
request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm."
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "template": {
    "id": "66c4f0a1b2c3d4e5f6a7b8c9",
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, see you at 3pm.",
    "created": 1755648000
  }
}
{
  "error": "Template limit reached (100)"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Update SMS Template

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Update a saved SMS template. Send only the fields you want to change: a field you omit keeps its stored value, and a JSON null reads as omitted. Neither field can be set to an empty string, because both are required on an SMS template.

Path parameters

Field Type Required Description
id string Yes Template id, 24 hex characters.

Request body parameters

Field Type Required Description
name string No New name, 100 characters or less.
text string No New message text, up to 4096 bytes.

Response fields

Same shape as Create SMS Template, reflecting the stored template after the update.

Errors

Error HTTP Cause
Invalid template ID 400 The path segment is not a 24 character hex id.
Template not found 400 No template with that id exists on this account.
No fields to update 400 Neither name nor text was sent.
Field name must be a string 400 name was sent as something other than a string.
Field text must be a string 400 text was sent as something other than a string.
Field text exceeds the 4096 byte limit 400 Message text too large.
Missing name 400 name was sent empty or whitespace only.
Name must be 100 characters or less 400 Name too long.
Missing text 400 text was sent empty or whitespace only.
Template not loaded 400 Internal guard; not reachable through this endpoint.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
id66c4f0a1b2c3d4e5f6a7b8c9Template id, 24 hex characters.
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/smstemplates/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi {{FirstName}}, your appointment moved to 4pm."
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/smstemplates/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "text": "Hi {{FirstName}}, your appointment moved to 4pm."
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "text": "Hi {{FirstName}}, your appointment moved to 4pm."
});

const req = https.request("https://www.5centsms.com.au/api/v5/smstemplates/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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/smstemplates/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "text": "Hi {{FirstName}}, your appointment moved to 4pm."
}'
]);
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 = """
{
    "text": "Hi {{FirstName}}, your appointment moved to 4pm."
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/smstemplates/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/smstemplates/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""text"": ""Hi {{FirstName}}, your appointment moved to 4pm.""
}", 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(`{
    "text": "Hi {{FirstName}}, your appointment moved to 4pm."
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/smstemplates/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/smstemplates/:id")
request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "text": "Hi {{FirstName}}, your appointment moved to 4pm."
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "template": {
    "id": "66c4f0a1b2c3d4e5f6a7b8c9",
    "name": "Appointment reminder",
    "text": "Hi {{FirstName}}, your appointment moved to 4pm.",
    "created": 1755648000
  }
}
{
  "error": "No fields to update"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete SMS Template

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Delete a saved SMS template. The delete is immediate and permanent. Messages already sent from the template are unaffected, because each send stores its own message text.

Path parameters

Field Type Required Description
id string Yes Template id, 24 hex characters.

Response fields

Field Type Description
message string Template deleted on success.
error string Empty on success.

Errors

Error HTTP Cause
Invalid template ID 400 The path segment is not a 24 character hex id.
Template not found 400 No template with that id exists on this account.
Template not loaded 400 Internal guard; not reachable through this endpoint.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
id66c4f0a1b2c3d4e5f6a7b8c9Template id, 24 hex characters.
Example Request
curl -X DELETE https://www.5centsms.com.au/api/v5/smstemplates/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/smstemplates/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/smstemplates/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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/smstemplates/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/smstemplates/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/smstemplates/:id")
request = Net::HTTP::Delete.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Template deleted"
}
{
  "error": "Template not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Conversations

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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations?per_page=50"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/conversations?per_page=50", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations?per_page=50"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations?per_page=50", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations?number=0412345678"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/conversations?number=0412345678", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations?number=0412345678"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations?number=0412345678", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/conversations/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/conversations/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/conversations/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

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

const req = https.request("https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

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("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations/:id?action=poll&since_mo=1749600120&since_mt=1749600060", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

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

const req = https.request("https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

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("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/conversations/:id?action=older&before_mo=1749600120&before_mt=1749600060", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 Conditional Plain-text body. Required unless TemplateID is supplied.
Html string No HTML body. Defaults to Text if omitted.
TemplateID string No Id of a saved email template (see List Email Templates). When present, Text and Html come from the template and must not be sent in the request.
TemplateModel object No Field name to value map used to fill {{FieldName}} and [#FieldName#] placeholders in Subject, Text and Html. Values must be strings or numbers.
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".

Templates and merge fields: save an HTML template in the dashboard (Email, then Templates) or with Create Email Template, using placeholders written as {{FieldName}} or [#FieldName#], then send it by passing TemplateID plus a TemplateModel of values. Placeholders are matched literally, so {{ FieldName }} with inner spaces will not be filled. Any placeholder your TemplateModel does not supply is removed from the message rather than delivered as raw text, and substitution runs against Subject as well as the bodies. TemplateModel also works on its own with an inline Text / Html body. Call Get Email Template to see which fields a template references. Substitution only happens when TemplateID or TemplateModel is present, so a body containing literal braces is untouched otherwise.

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.
Provide either TemplateID or Text/Html, not both 400 TemplateID was sent together with Text or Html.
Invalid TemplateID 400 TemplateID is not a 24 character hex id.
Template not found 400 No template with that id exists on this account.
Template has no content 400 The template has neither HTML nor plain-text content.
TemplateModel must be an object of field name to value 400 TemplateModel was not sent as an object.
TemplateModel values must be strings or numbers 400 A TemplateModel value is an array, object, or boolean.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/email \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome {{firstName}}",
    "TemplateID": "66c4f0a1b2c3d4e5f6a7b8c9",
    "TemplateModel": {
        "firstName": "Jane",
        "orderId": "10482"
    },
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/email"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome {{firstName}}",
    "TemplateID": "66c4f0a1b2c3d4e5f6a7b8c9",
    "TemplateModel": {
        "firstName": "Jane",
        "orderId": "10482"
    },
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome {{firstName}}",
    "TemplateID": "66c4f0a1b2c3d4e5f6a7b8c9",
    "TemplateModel": {
        "firstName": "Jane",
        "orderId": "10482"
    },
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
});

const req = https.request("https://api.dingomail.com.au/api/v5/email", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome {{firstName}}",
    "TemplateID": "66c4f0a1b2c3d4e5f6a7b8c9",
    "TemplateModel": {
        "firstName": "Jane",
        "orderId": "10482"
    },
    "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 = """
{
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome {{firstName}}",
    "TemplateID": "66c4f0a1b2c3d4e5f6a7b8c9",
    "TemplateModel": {
        "firstName": "Jane",
        "orderId": "10482"
    },
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""SenderEmail"": ""news@mail.example.com"",
    ""SenderName"": ""Example"",
    ""Subject"": ""Welcome {{firstName}}"",
    ""TemplateID"": ""66c4f0a1b2c3d4e5f6a7b8c9"",
    ""TemplateModel"": {
        ""firstName"": ""Jane"",
        ""orderId"": ""10482""
    },
    ""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(`{
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome {{firstName}}",
    "TemplateID": "66c4f0a1b2c3d4e5f6a7b8c9",
    "TemplateModel": {
        "firstName": "Jane",
        "orderId": "10482"
    },
    "Recipient": "jane@example.com",
    "ReplyTo": "support@example.com"
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/email", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "SenderEmail": "news@mail.example.com",
    "SenderName": "Example",
    "Subject": "Welcome {{firstName}}",
    "TemplateID": "66c4f0a1b2c3d4e5f6a7b8c9",
    "TemplateModel": {
        "firstName": "Jane",
        "orderId": "10482"
    },
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/email"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/email", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/email"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/email", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/email/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/email/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/email/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/email/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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.

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.
include_archived boolean No Set to 1 to include archived inbound email. Excluded by default.

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[].from_name string Sender display name, decoded to UTF-8. Empty when the sender supplied none, and on email received before this field shipped.
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[].archived boolean True when the account has archived this email. Only ever true when include_archived is set.
emails[].authentication object Sender-authentication outcome for the email. Always present.
emails[].authentication.available boolean False when the message arrived without a trustworthy authentication assessment; every result then reads unknown.
emails[].authentication.spf.result string One of pass, fail, softfail, neutral, none, temperror, permerror, unknown.
emails[].authentication.spf.domain string Envelope-sender domain SPF was evaluated against.
emails[].authentication.spf.client_ip string IP address the message was delivered from.
emails[].authentication.spf.helo string HELO/EHLO name the sending host presented.
emails[].authentication.spf.envelope_from string Envelope sender (return path) address.
emails[].authentication.dkim.result string Same enum as spf.result. When the sender applied more than one signature, this is the result for the first one evaluated; dkim.signatures lists them all.
emails[].authentication.dkim.domain string Signing domain of the DKIM signature this result refers to.
emails[].authentication.dkim.selector string Selector of that signature. Empty when it could not be matched.
emails[].authentication.dkim.algorithm string rsa-sha256, rsa-sha1 or ed25519-sha256. Empty when not recognised.
emails[].authentication.dkim.signatures array Every DKIM signature the sender applied: domain, selector, algorithm. Empty for unsigned mail.
emails[].authentication.dmarc.result string Same enum as spf.result.
emails[].authentication.dmarc.from_domain string Domain of the From header, which is what DMARC evaluates.
emails[].authentication.dmarc.alignment.spf boolean True when spf.domain matches dmarc.from_domain exactly or as a subdomain.
emails[].authentication.dmarc.alignment.dkim boolean True when dkim.domain matches dmarc.from_domain exactly or as a subdomain.
emails[].authentication.hops integer Number of relay hops recorded on the message.
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.
Mailbox Not Found 400 mailbox_address is not a hosted mailbox on your account.
Unsupported method 400 The collection route was called with DELETE, or with POST (POST is only valid on /inboundemail/{id}).

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 mailbox_address filter, and include_archived. The paging examples below use limit=2 to stay short.
  • mailbox_address must be one of your own hosted mailboxes. An address that does not exist, or that belongs to another account, returns Mailbox Not Found rather than an empty list, so a typo is not mistaken for an empty mailbox. Plus-addressed forms such as sales+tag@… are not mailboxes and are rejected for the same reason; filter on the base address. A mailbox you have disabled is still accepted, so its earlier inbound stays listable.
  • Archived inbound email is excluded from this list. Pass include_archived=1 to include it; next_page echoes the flag. Archive with POST /inboundemail/{id}. Archiving cannot be reversed.
  • authentication reports what sender authentication produced for the message as it arrived. It is reporting only: inbound email is never rejected, quarantined or altered on the basis of these results, and a fail on any of the three still appears in this list and is still delivered to your webhook.
  • Alignment is relaxed and suffix-based: mail.example.com aligns with example.com, but two sibling registrable domains never align. It is not evaluated against the Public Suffix List.
  • available: false means no trustworthy assessment accompanied the message. It is the value returned for a message whose only authentication header came from an untrusted source. It is not itself an authentication failure.
  • spf.domain and spf.envelope_from can both be empty while spf.result is populated, which is normal for a message with a null return path such as a bounce.

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.
include_archived1Optional. Set to 1 to include archived inbound email. Archived email is excluded by default.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/inboundemail \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/inboundemail"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/inboundemail", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/inboundemail"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/inboundemail", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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",
      "from_name": "Jane Smith",
      "to": "support@mail.example.com",
      "subject": "Re: Welcome",
      "has_attachments": false,
      "archived": false,
      "authentication": {
        "available": true,
        "spf": { "result": "pass", "domain": "example.com", "client_ip": "209.85.214.180", "helo": "mail-pl1-f180.google.com", "envelope_from": "jane@example.com" },
        "dkim": { "result": "pass", "domain": "example.com", "selector": "google", "algorithm": "rsa-sha256", "signatures": [ { "domain": "example.com", "selector": "google", "algorithm": "rsa-sha256" } ] },
        "dmarc": { "result": "pass", "from_domain": "example.com", "alignment": { "spf": true, "dkim": true } },
        "hops": 3
      },
      "created_at": 1717000000
    },
    {
      "id": "683554c596937cc4b90f5cf5",
      "from": "tom@example.com",
      "from_name": "",
      "to": "hello@mail.example.com",
      "subject": "Invoice attached",
      "has_attachments": true,
      "archived": false,
      "authentication": {
        "available": true,
        "spf": { "result": "fail", "domain": "example.com", "client_ip": "198.51.100.24", "helo": "mail.spoofer.example", "envelope_from": "tom@example.com" },
        "dkim": { "result": "none", "domain": "", "selector": "", "algorithm": "", "signatures": [] },
        "dmarc": { "result": "fail", "from_domain": "example.com", "alignment": { "spf": true, "dkim": false } },
        "hops": 2
      },
      "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",
      "from_name": "Amy Jones",
      "to": "support@mail.example.com",
      "subject": "Question about my order",
      "has_attachments": false,
      "archived": false,
      "authentication": {
        "available": false,
        "spf": { "result": "unknown", "domain": "", "client_ip": "", "helo": "", "envelope_from": "" },
        "dkim": { "result": "unknown", "domain": "", "selector": "", "algorithm": "", "signatures": [] },
        "dmarc": { "result": "unknown", "from_domain": "", "alignment": { "spf": false, "dkim": false } },
        "hops": 0
      },
      "created_at": 1716998000
    }
  ],
  "count": 1
}
{
  "error": "",
  "emails": [
    {
      "id": "683554c596937cc4b90f5cf7",
      "from": "jane@example.com",
      "from_name": "Jane Smith",
      "to": "support@mail.example.com",
      "subject": "Re: Welcome",
      "has_attachments": false,
      "archived": false,
      "authentication": {
        "available": true,
        "spf": { "result": "pass", "domain": "example.com", "client_ip": "209.85.214.180", "helo": "mail-pl1-f180.google.com", "envelope_from": "jane@example.com" },
        "dkim": { "result": "pass", "domain": "example.com", "selector": "google", "algorithm": "rsa-sha256", "signatures": [ { "domain": "example.com", "selector": "google", "algorithm": "rsa-sha256" } ] },
        "dmarc": { "result": "pass", "from_domain": "example.com", "alignment": { "spf": true, "dkim": true } },
        "hops": 3
      },
      "created_at": 1717000000
    },
    {
      "id": "683554c596937cc4b90f5cf5",
      "from": "tom@example.com",
      "from_name": "",
      "to": "hello@mail.example.com",
      "subject": "Invoice attached",
      "has_attachments": true,
      "archived": true,
      "authentication": {
        "available": true,
        "spf": { "result": "fail", "domain": "example.com", "client_ip": "198.51.100.24", "helo": "mail.spoofer.example", "envelope_from": "tom@example.com" },
        "dkim": { "result": "none", "domain": "", "selector": "", "algorithm": "", "signatures": [] },
        "dmarc": { "result": "fail", "from_domain": "example.com", "alignment": { "spf": true, "dkim": false } },
        "hops": 2
      },
      "mailbox_address": "hello@mail.example.com",
      "created_at": 1716999000
    }
  ],
  "count": 2,
  "next_page": "/api/v5/inboundemail?after=683554c596937cc4b90f5cf5&include_archived=1&limit=2"
}
{
  "error": "Mailbox Not Found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Inbound Email

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

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

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.from_name string Sender display name, decoded to UTF-8. Empty when the sender supplied none, and on email received before this field shipped.
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.archived boolean True when the account has archived this email. Archived email stays fully readable through this endpoint.
email.archived_at integer Epoch seconds of the archive request. Present only when archived is true.
email.authentication object Sender-authentication outcome for the email. Always present.
email.authentication.available boolean False when the message arrived without a trustworthy authentication assessment; every result then reads unknown.
email.authentication.spf.result string One of pass, fail, softfail, neutral, none, temperror, permerror, unknown.
email.authentication.spf.domain string Envelope-sender domain SPF was evaluated against.
email.authentication.spf.client_ip string IP address the message was delivered from.
email.authentication.spf.helo string HELO/EHLO name the sending host presented.
email.authentication.spf.envelope_from string Envelope sender (return path) address.
email.authentication.dkim.result string Same enum as spf.result. When the sender applied more than one signature, this is the result for the first one evaluated; dkim.signatures lists them all.
email.authentication.dkim.domain string Signing domain of the DKIM signature this result refers to.
email.authentication.dkim.selector string Selector of that signature. Empty when it could not be matched.
email.authentication.dkim.algorithm string rsa-sha256, rsa-sha1 or ed25519-sha256. Empty when not recognised.
email.authentication.dkim.signatures array Every DKIM signature the sender applied: domain, selector, algorithm. Empty for unsigned mail.
email.authentication.dmarc.result string Same enum as spf.result.
email.authentication.dmarc.from_domain string Domain of the From header, which is what DMARC evaluates.
email.authentication.dmarc.alignment.spf boolean True when spf.domain matches dmarc.from_domain exactly or as a subdomain.
email.authentication.dmarc.alignment.dkim boolean True when dkim.domain matches dmarc.from_domain exactly or as a subdomain.
email.authentication.hops integer Number of relay hops recorded on the message.
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 DELETE. POST on this route archives (see Archive Inbound Email).

Notes

  • authentication reports what sender authentication produced for the message as it arrived. It is reporting only: inbound email is never rejected, quarantined or altered on the basis of these results.
  • Alignment is relaxed and suffix-based: mail.example.com aligns with example.com, but two sibling registrable domains never align. It is not evaluated against the Public Suffix List.
  • available: false means no trustworthy assessment accompanied the message. It is the value returned for a message whose only authentication header came from an untrusted source. It is not itself an authentication failure.
  • spf.domain and spf.envelope_from can both be empty while spf.result is populated, which is normal for a message with a null return path such as a bounce.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/inboundemail/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/inboundemail/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/inboundemail/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/inboundemail/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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",
    "from_name": "Jane Smith",
    "to": "support@mail.example.com",
    "subject": "Re: Welcome",
    "text": "Thanks!",
    "html": "<p>Thanks!</p>",
    "attachments": [],
    "archived": false,
    "authentication": {
      "available": true,
      "spf": { "result": "pass", "domain": "example.com", "client_ip": "209.85.214.180", "helo": "mail-pl1-f180.google.com", "envelope_from": "jane@example.com" },
      "dkim": { "result": "pass", "domain": "example.com", "selector": "google", "algorithm": "rsa-sha256", "signatures": [ { "domain": "example.com", "selector": "google", "algorithm": "rsa-sha256" } ] },
      "dmarc": { "result": "pass", "from_domain": "example.com", "alignment": { "spf": true, "dkim": true } },
      "hops": 3
    },
    "created_at": 1717000000
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Archive Inbound Email

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Archive one received email. Archiving hides the email from GET /inboundemail unless that call passes include_archived=1; it never deletes the email or its attachments, does not change its one-year retention, and the email stays fully readable through GET /inboundemail/{id}.

Archiving is permanent. There is no unarchive operation, on this endpoint or in the dashboard. Sending archived: false returns Unarchiving is not supported.

Request body

Field Type Required Description
archived boolean Yes Must be truthy (true, 1, "true"). A falsy value is rejected - archiving cannot be reversed.

Path parameters

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

Response fields

Field Type Description
error string Empty on success.
message string Inbound email archived.
id string The inbound email id acted on.
archived boolean Always true on success.

Errors

Error HTTP Cause
Invalid inbound email ID 400 id is not a valid 24-hex id.
archived Required. Please see our API Docs 400 The body has no archived field.
Unarchiving is not supported 400 archived was sent as false, 0, "false", or null.
Inbound email not found 400 No such inbound email, or not owned by this account.
Unsupported method 400 POSTed to /inboundemail with no id.

Notes

  • Idempotent: re-archiving an already-archived email succeeds and returns the same body. It refreshes archived_at to the time of the latest request.
  • Archiving is free and does not touch the email quota.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
idInbound email id.
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/inboundemail/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "archived": true
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/inboundemail/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "archived": true
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "archived": true
});

const req = https.request("https://api.dingomail.com.au/api/v5/inboundemail/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "archived": true
}'
]);
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 = """
{
    "archived": true
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/inboundemail/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/inboundemail/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""archived"": true
}", 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(`{
    "archived": true
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/inboundemail/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "archived": true
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Inbound email archived",
  "id": "683554c596937cc4b90f5cf7",
  "archived": true
}
{
  "error": "Unarchiving is not supported"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Email Templates

GET https://api.dingomail.com.au/api/v5/emailtemplates?limit=2

Send Authorization: Bearer <key-id>:<key-secret> on every request.

List the saved email templates on your account, newest first. Templates can be created and edited in the dashboard (Email, then Templates) or over this API. Pass a template's id as TemplateID on Send Email.

Query parameters

Field Type Required Description
limit integer No Rows per page, 1 to 100. Defaults to 20.
after string No Cursor: the id of the last template on the previous page. Returns older templates only.

next_page is present only when a full page was returned, so paginate until it is absent. An account can hold at most 100 templates.

Response fields

Field Type Description
templates array One object per template.
templates[].id string Template id.
templates[].name string Template name.
templates[].created integer Unix timestamp the template was created, or null on a legacy document with no stored timestamp.
count integer Number of templates returned.
next_page string Path to the next page, present only when a full page was returned.
error string Empty on success.

Errors

Error HTTP Cause
Invalid after parameter 400 after is not a 24 character hex id.
Invalid limit parameter 400 limit is not numeric.

Authentication errors are listed in the intro's 401 table.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
limit2Rows per page, 1 to 100. Defaults to 20.
afterCursor: id of the last template on the previous page.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/emailtemplates?limit=2 \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/emailtemplates?limit=2"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/emailtemplates?limit=2"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/emailtemplates?limit=2");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/emailtemplates?limit=2", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/emailtemplates?limit=2")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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,
  "templates": [
    {
      "id": "66c4f0a1b2c3d4e5f6a7b8c9",
      "name": "Order confirmation",
      "created": 1755648000
    },
    {
      "id": "66b2e1f0a1b2c3d4e5f6a7b8",
      "name": "Password reset",
      "created": 1753142400
    }
  ],
  "next_page": "/api/v5/emailtemplates?after=66b2e1f0a1b2c3d4e5f6a7b8&limit=2"
}
{
  "error": "",
  "count": 1,
  "templates": [
    {
      "id": "66a0d0e0f1a2b3c4d5e6f7a8",
      "name": "Welcome",
      "created": 1750464000
    }
  ]
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Email Template

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Fetch one template with its content, plus the merge fields it references so you know what TemplateModel has to supply on Send Email.

Path parameters

Field Type Required Description
id string Yes Template id, 24 hex characters.

Response fields

Field Type Description
template.id string Template id.
template.name string Template name.
template.html_content string HTML body stored on the template. Empty string when the template is plain text only.
template.plain_content string Plain-text body stored on the template. Empty string when the template is HTML only.
template.created integer Unix timestamp the template was created.
template.merge_fields array Distinct field names referenced by the template, in first-seen order across the HTML then plain-text content. Supply each as a key of TemplateModel.
error string Empty on success.

Errors

Error HTTP Cause
Invalid template ID 400 The path segment is not a 24 character hex id.
Template not found 400 No template with that id exists on this account.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
id66c4f0a1b2c3d4e5f6a7b8c9Template id, 24 hex characters.
Example Request
curl -X GET https://api.dingomail.com.au/api/v5/emailtemplates/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/emailtemplates/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/emailtemplates/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/emailtemplates/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/emailtemplates/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/emailtemplates/:id")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "template": {
    "id": "66c4f0a1b2c3d4e5f6a7b8c9",
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way.",
    "created": 1755648000,
    "merge_fields": [
      "firstName",
      "orderId"
    ]
  }
}
{
  "error": "Template not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Email Template

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Create a saved email template. Write placeholders as {{FieldName}} or [#FieldName#] and fill them at send time with Send Email's TemplateModel.

Request body parameters

Field Type Required Description
name string Yes Template name, 100 characters or less. Names need not be unique.
html_content string Conditional HTML body. At least one of html_content / plain_content is required, each limited to 524288 bytes.
plain_content string Conditional Plain-text body.

Response fields

Field Type Description
template.id string New template id. Pass as TemplateID on Send Email.
template.name string Stored name, trimmed.
template.html_content string Stored HTML body.
template.plain_content string Stored plain-text body.
template.created integer Unix timestamp the template was created.
template.merge_fields array Distinct field names the template references.
error string Empty on success.

Errors

Error HTTP Cause
Required parameter: name missing 400 name was not sent.
Required parameter: html_content or plain_content missing 400 Neither body was sent.
Field name must be a string 400 name was sent as something other than a string.
Field html_content must be a string 400 html_content was sent as something other than a string.
Field plain_content must be a string 400 plain_content was sent as something other than a string.
Field html_content exceeds the 524288 byte limit 400 HTML body too large.
Field plain_content exceeds the 524288 byte limit 400 Plain-text body too large.
Template limit reached (100) 400 The account already holds 100 templates. Delete one first.
Missing name 400 name is empty or whitespace only.
Name must be 100 characters or less 400 Name too long.
At least one of html_content or plain_content is required 400 Both bodies are empty strings.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/emailtemplates \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way."
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/emailtemplates"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way."
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way."
});

const req = https.request("https://api.dingomail.com.au/api/v5/emailtemplates", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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/emailtemplates");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way."
}'
]);
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 = """
{
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way."
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/emailtemplates"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/emailtemplates");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""name"": ""Order confirmation"",
    ""html_content"": ""<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>"",
    ""plain_content"": ""Hi {{firstName}}, order {{orderId}} is on its way.""
}", 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(`{
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way."
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/emailtemplates", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/emailtemplates")
request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way."
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "template": {
    "id": "66c4f0a1b2c3d4e5f6a7b8c9",
    "name": "Order confirmation",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} is on its way.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way.",
    "created": 1755648000,
    "merge_fields": [
      "firstName",
      "orderId"
    ]
  }
}
{
  "error": "Template limit reached (100)"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Update Email Template

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Update a saved template. Send only the fields you want to change: a field you omit keeps its stored value. To clear one side of the content, send it as an empty string; a JSON null reads as omitted, not as a clear. A template cannot be left with both bodies empty.

Path parameters

Field Type Required Description
id string Yes Template id, 24 hex characters.

Request body parameters

Field Type Required Description
name string No New name, 100 characters or less.
html_content string No New HTML body, up to 524288 bytes. Empty string clears it.
plain_content string No New plain-text body, up to 524288 bytes. Empty string clears it.

Response fields

Same shape as Create Email Template, reflecting the stored template after the update.

Errors

Error HTTP Cause
Invalid template ID 400 The path segment is not a 24 character hex id.
Template not found 400 No template with that id exists on this account.
No fields to update 400 None of name / html_content / plain_content was sent.
Field name must be a string 400 name was sent as something other than a string.
Field html_content must be a string 400 html_content was sent as something other than a string.
Field plain_content must be a string 400 plain_content was sent as something other than a string.
Field html_content exceeds the 524288 byte limit 400 HTML body too large.
Field plain_content exceeds the 524288 byte limit 400 Plain-text body too large.
Missing name 400 name was sent empty or whitespace only.
Name must be 100 characters or less 400 Name too long.
At least one of html_content or plain_content is required 400 The update would leave the template with no body.
Template not loaded 400 Internal guard; not reachable through this endpoint.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
id66c4f0a1b2c3d4e5f6a7b8c9Template id, 24 hex characters.
Example Request
curl -X POST https://api.dingomail.com.au/api/v5/emailtemplates/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>"
}'
import requests
import json

url = "https://api.dingomail.com.au/api/v5/emailtemplates/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>"
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>"
});

const req = https.request("https://api.dingomail.com.au/api/v5/emailtemplates/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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/emailtemplates/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>"
}'
]);
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 = """
{
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/emailtemplates/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/emailtemplates/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""name"": ""Order confirmation v2"",
    ""html_content"": ""<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>""
}", 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(`{
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>"
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/emailtemplates/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/emailtemplates/:id")
request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "template": {
    "id": "66c4f0a1b2c3d4e5f6a7b8c9",
    "name": "Order confirmation v2",
    "html_content": "<p>Hi {{firstName}}, order {{orderId}} has shipped.</p>",
    "plain_content": "Hi {{firstName}}, order {{orderId}} is on its way.",
    "created": 1755648000,
    "merge_fields": [
      "firstName",
      "orderId"
    ]
  }
}
{
  "error": "At least one of html_content or plain_content is required"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Email Template

DELETE https://api.dingomail.com.au/api/v5/emailtemplates/:id

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Delete a saved template. The delete is immediate and permanent. Emails already sent from the template are unaffected, because each send stores its own rendered copy, and a campaign built from the template is unaffected too, because the campaign builder copies the content into the campaign at build time.

Path parameters

Field Type Required Description
id string Yes Template id, 24 hex characters.

Response fields

Field Type Description
message string Template deleted on success.
error string Empty on success.

Errors

Error HTTP Cause
Invalid template ID 400 The path segment is not a 24 character hex id.
Template not found 400 No template with that id exists on this account.
Template not loaded 400 Internal guard; not reachable through this endpoint.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Path variables

VariableExampleDescription
id66c4f0a1b2c3d4e5f6a7b8c9Template id, 24 hex characters.
Example Request
curl -X DELETE https://api.dingomail.com.au/api/v5/emailtemplates/:id \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/emailtemplates/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/emailtemplates/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.end();
<?php
$ch = curl_init("https://api.dingomail.com.au/api/v5/emailtemplates/:id");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/emailtemplates/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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://api.dingomail.com.au/api/v5/emailtemplates/:id");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.dingomail.com.au/api/v5/emailtemplates/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/emailtemplates/:id")
request = Net::HTTP::Delete.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "Template deleted"
}
{
  "error": "Template not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get Balance

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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/balance"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/balance", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/balance"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/balance", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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)"
}

GET Get Email Usage

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Returns this account's monthly email and attachment-data allowances, how much of each has been consumed so far this month, and when the counters next reset.

Response fields

Field Type Description
error string Empty on success.
usage.email.quota integer Monthly email allowance. 0 means no email plan.
usage.email.used integer Emails counted this month. One message counts one unit whether it was sent or received.
usage.email.percent number used / quota as a percentage, one decimal place, capped at 100. 0 when quota is 0.
usage.attachment_data.enabled boolean Whether the account has the attachment feature. Usage is reported either way.
usage.attachment_data.quota_mb integer Monthly attachment-data allowance in MB. 0 means an allowance of zero, not unlimited.
usage.attachment_data.used_mb number Attachment bytes transferred this month, in MB to one decimal place. Counts data sent (per recipient) and received. Not the size of stored attachments.
usage.attachment_data.percent number used_mb / quota_mb as a percentage, one decimal place, capped at 100. 100 when quota_mb is 0 and any data has been transferred.
usage.next_renewal integer|null Unix timestamp of the next reset, or null when nothing resets this account.
usage.next_renewal_date string|null The same instant as YYYY-MM-DD, in the platform's timezone, or null. This is the same date the account sees on its dashboard.

Notes

  • Both counters are monthly and reset at the renewal. An account with neither a subscription nor postpaid / free-developer billing has no reset, so its figures are cumulative and next_renewal is null.
  • Quotas are not enforced. Exceeding either one is reported here and blocks nothing.
  • percent is provided so clients need not reimplement the zero-quota rule.

Errors

Error HTTP Cause
Unsupported method. Please see our API Docs 400 A POST or DELETE was sent. This endpoint is GET only.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/emailusage \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/emailusage"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/emailusage"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/emailusage");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/emailusage", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/emailusage")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "usage": {
    "email": {
      "quota": 50000,
      "used": 34120,
      "percent": 68.2
    },
    "attachment_data": {
      "enabled": true,
      "quota_mb": 1024,
      "used_mb": 412.8,
      "percent": 40.3
    },
    "next_renewal": 1790820000,
    "next_renewal_date": "2026-10-01"
  }
}
{
  "error": "",
  "usage": {
    "email": {
      "quota": 0,
      "used": 0,
      "percent": 0
    },
    "attachment_data": {
      "enabled": false,
      "quota_mb": 0,
      "used_mb": 0,
      "percent": 0
    },
    "next_renewal": null,
    "next_renewal_date": null
  }
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Pre-warm Send Queue

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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/prewarm"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("POST", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/prewarm", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/prewarm"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/prewarm", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "admin"
}'
import requests
import json

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

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

const req = https.request("https://www.5centsms.com.au/api/v5/logins", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/logins"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/logins", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/logins"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/logins", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "change_role",
    "role": "manager"
}'
import requests
import json

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

const body = JSON.stringify({
    "action": "change_role",
    "role": "manager"
});

const req = https.request("https://www.5centsms.com.au/api/v5/logins/:login_id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "action": "change_role",
    "role": "manager"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/logins/:login_id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/logins/:login_id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/logins/:login_id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/logins/:login_id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/logins/:login_id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 (email / both). Validated when stored: it must be one of your active hosted mailboxes, or an address at one of your validated sending domains. Pass an empty string to clear.
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).
email_template_id string No 24-char hex id of one of your email templates. Copies the template's HTML and plain-text content into email_body / email_text. Cannot be combined with email_body or email_text in the same request.
sms_template_id string No 24-char hex id of one of your SMS templates. Copies the template's text into sms_body. Cannot be combined with sms_body in the same request.
attachment_urls array No Email attachments, each an object {"url": "...", "filename": "..."} (url required, filename optional). Requires the attachments account feature. Maximum 5. Pass [] to clear. See the attachment note below.
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. Returned even when error reports a settings failure, so you can retry or delete the draft.
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.
Provide either email_template_id or email_body/email_text, not both 400 email_template_id supplied alongside a literal email body.
Invalid email_template_id format 400 email_template_id is not a 24-char hex id.
Email template not found 400 No such email template on this account.
Provide either sms_template_id or sms_body, not both 400 sms_template_id supplied alongside sms_body.
Invalid sms_template_id format 400 sms_template_id is not a 24-char hex id.
SMS template not found 400 No such SMS template on this account.
Template has no content 400 The referenced template's body is empty.
attachment_urls must be an array 400 attachment_urls was not an array.
Attachments not enabled for this account 400 Non-empty attachment_urls without the attachments account feature.
Maximum 5 attachments allowed 400 More than 5 entries in attachment_urls.
Each attachment must have a url field 400 An attachment_urls entry is not an object carrying a non-empty url.
Sender email is not a valid email address. 400 sender_email is not a parseable address.
Sender email must be one of your active mailboxes. 400 sender_email is on the hosted mailbox domain but is not an active mailbox you own.
Sender email must use one of your validated domains. 400 sender_email's domain is not a validated sending domain on this account.
No recipients provided 400 numbers/emails/contact_list_ids supplied but all empty.
You need an active email plan to send email campaigns 400 Inline send on an email campaign without email quota.
You need a verified domain to send email campaigns 400 Inline send on an email campaign with no validated domain.
You need SMS credits or a postpaid account to send SMS campaigns 400 Inline send on an SMS campaign with no balance.
No recipients added 400 Inline send with no recipients on the campaign.
Sender email is required / Sender name is required / Subject line is required / Email body is required 400 Inline send of an incomplete email campaign.
SMS sender ID is required / SMS message body is required 400 Inline send of an incomplete SMS campaign.
Unicode SMS message is too long (max 335 characters) 400 Inline send; unicode body over the limit.
SMS message is too long (max 765 characters) 400 Inline send; GSM body over the limit.
Scheduled time must be in the future 400 schedule resolves to a past time.
Failed to start campaign 400 The send could not be queued.

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.

Note — attachments are fetched once, when the campaign starts. Each URL in attachment_urls is downloaded a single time as the campaign begins sending, stored, and attached to every recipient's email from our storage — your server is not contacted once per recipient. The URL must be publicly reachable at that moment. If any download fails, a single file exceeds 10 MB, or the files total more than 25 MB, the whole campaign stops before any message is sent, returns to DRAFT, and the reason appears in the campaign's send_error field (see Get campaign). Attachments uploaded in the dashboard count toward the same 5-file and 25 MB limits.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/campaigns \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "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, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "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: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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?limit=200

Send Authorization: Bearer <key-id>:<key-secret> on every request.

List your account's campaigns, most-recent-first, with keyset pagination. Campaigns are purged 365 days after creation.

Query parameters

Field Type Required Description
after string No Cursor: the campaign_id of the last campaign on the previous page. Omit for the first page.
limit integer No Page size, 1–200. Default 200.

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.
next_page string Root-relative path to the next page — /api/v5/campaigns?after=<last_id>, plus &limit= when non-default. Present only when a full page was returned (count equals limit); absent on the last page.

Errors

Error HTTP Cause
Invalid after parameter 400 after is not a 24-char hex id.
Invalid limit parameter 400 limit is not numeric.

Paging. Follow next_page until it is absent. Because it appears only on a full page, a final page holding exactly limit rows costs one extra request that comes back empty — that is expected.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
afterCursor: the campaign_id of the last campaign on the previous page. Omit for the first page.
limit200Page size, 1-200. Default 200.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/campaigns?limit=200 \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns?limit=200"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns?limit=200"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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?limit=200");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/campaigns?limit=200", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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?limit=200")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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
    },
    {
      "campaign_id": "665f1a2b3c4d5e6f7a8b9c07",
      "title": "June newsletter",
      "status": "SENT",
      "type": [
        "email"
      ],
      "recipient_count": 1820,
      "schedule": null
    }
  ],
  "count": 2,
  "next_page": "/api/v5/campaigns?after=665f1a2b3c4d5e6f7a8b9c07&limit=2"
}
{
  "error": "",
  "campaigns": [
    {
      "campaign_id": "665f1a2b3c4d5e6f7a8b9c01",
      "title": "May promo",
      "status": "SENT",
      "type": [
        "sms"
      ],
      "recipient_count": 96,
      "schedule": null
    }
  ],
  "count": 1
}
{
  "error": "Invalid after parameter"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get campaign

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

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

For a lightweight stats-only read use Get campaign stats. To page through every recipient use Get campaign recipients.

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.
send_error string Why the last send attempt aborted, or null. Set when a campaign is returned to DRAFT because its attachments could not be prepared; cleared automatically on the next send.
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, attachment_urls.
recipients array The first 100 recipient rows, newest first. Each row: id, type (individual/contact_list), and either recipient_type+value or contact_list_id+contact_list_name+contact_list_count, plus created.
recipients_next_page string Root-relative path into Get campaign recipients for the rows beyond the first 100. Present only when 100 rows were returned.
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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/campaigns/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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,
  "send_error": null,
  "sms": {
    "sender_id": "EXAMPLE",
    "body": "Hello {{FirstName}}, from Acme!",
    "optout_enabled": true,
    "unicode_enabled": false
  },
  "recipients": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c11",
      "type": "contact_list",
      "created": 1719792000,
      "contact_list_id": "665f1a2b3c4d5e6f7a8b9c10",
      "contact_list_name": "Newsletter",
      "contact_list_count": 240
    }
  ],
  "stats": {
    "type": "sms",
    "sms": {
      "total": 240,
      "queued": 0,
      "sent": 12,
      "delivered": 226,
      "failed": 2
    }
  }
}
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c1f",
  "title": "August newsletter",
  "status": "SENDING",
  "type": [
    "email"
  ],
  "recipient_count": 1820,
  "schedule": null,
  "send_error": null,
  "email": {
    "sender_email": "news@mail.example.com",
    "sender_name": "Example",
    "subject": "Hello {{FirstName}}",
    "has_body": true,
    "attachment_urls": [
      {
        "url": "https://example.com/august.pdf",
        "filename": "august.pdf"
      }
    ]
  },
  "recipients": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c90",
      "type": "individual",
      "created": 1719792100,
      "recipient_type": "email",
      "value": "person0@example.com"
    },
    {
      "id": "665f1a2b3c4d5e6f7a8b9c8f",
      "type": "individual",
      "created": 1719792099,
      "recipient_type": "email",
      "value": "person1@example.com"
    },
    "\u2026 98 more rows \u2026"
  ],
  "recipients_next_page": "/api/v5/campaigns/665f1a2b3c4d5e6f7a8b9c1f/recipients?after=665f1a2b3c4d5e6f7a8b9c2d",
  "stats": {
    "type": "email",
    "email": {
      "total": 1820,
      "queued": 400,
      "sent": 1420,
      "delivered": 1390,
      "bounced": 22,
      "failed": 8
    }
  }
}
{
  "error": "Campaign not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Update campaign

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

Send Authorization: Bearer <key-id>:<key-secret> on 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. Validated when stored: it must be one of your active hosted mailboxes, or an address at one of your validated sending domains. Pass an empty string to clear.
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.
email_template_id string No 24-char hex id of one of your email templates. Copies the template's HTML and plain-text content into email_body / email_text. Cannot be combined with email_body or email_text in the same request.
sms_template_id string No 24-char hex id of one of your SMS templates. Copies the template's text into sms_body. Cannot be combined with sms_body in the same request.
attachment_urls array No Email attachments, each an object {"url": "...", "filename": "..."} (url required, filename optional). Requires the attachments account feature. Maximum 5. Pass [] to clear. See the attachment note below.

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.
Provide either email_template_id or email_body/email_text, not both 400 email_template_id supplied alongside a literal email body.
Invalid email_template_id format 400 email_template_id is not a 24-char hex id.
Email template not found 400 No such email template on this account.
Provide either sms_template_id or sms_body, not both 400 sms_template_id supplied alongside sms_body.
Invalid sms_template_id format 400 sms_template_id is not a 24-char hex id.
SMS template not found 400 No such SMS template on this account.
Template has no content 400 The referenced template's body is empty.
attachment_urls must be an array 400 attachment_urls was not an array.
Attachments not enabled for this account 400 Non-empty attachment_urls without the attachments account feature.
Maximum 5 attachments allowed 400 More than 5 entries in attachment_urls.
Each attachment must have a url field 400 An attachment_urls entry is not an object carrying a non-empty url.
Sender email is not a valid email address. 400 sender_email is not a parseable address.
Sender email must be one of your active mailboxes. 400 sender_email is on the hosted mailbox domain but is not an active mailbox you own.
Sender email must use one of your validated domains. 400 sender_email's domain is not a validated sending domain on this account.

Note — attachments are fetched once, when the campaign starts. Each URL in attachment_urls is downloaded a single time as the campaign begins sending, stored, and attached to every recipient's email from our storage — your server is not contacted once per recipient. The URL must be publicly reachable at that moment. If any download fails, a single file exceeds 10 MB, or the files total more than 25 MB, the whole campaign stops before any message is sent, returns to DRAFT, and the reason appears in the campaign's send_error field (see Get campaign). Attachments uploaded in the dashboard count toward the same 5-file and 25 MB limits.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "action": "update",
    "title": "July promo (final)",
    "sms_body": "Hello from Acme! Reply STOP to opt out."
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "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: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_recipients",
    "numbers": [
        "0404123123",
        "0404123124"
    ],
    "contact_list_ids": [
        "683554c596937cc4b90f5cf7"
    ]
}'
import requests
import json

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

const body = JSON.stringify({
    "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: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}'
import requests
import json

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

const body = JSON.stringify({
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "action": "remove_recipient",
    "recipient_id": "665f1a2b3c4d5e6f7a8b9c11"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "clear_recipients"
}'
import requests
import json

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

const body = JSON.stringify({
    "action": "clear_recipients"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "action": "clear_recipients"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "action": "clear_recipients"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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). 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.
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-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 765 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send"
}'
import requests
import json

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

const body = JSON.stringify({
    "action": "send"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "action": "send"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "action": "send"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "cancel_schedule"
}'
import requests
import json

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

const body = JSON.stringify({
    "action": "cancel_schedule"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "action": "cancel_schedule"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "action": "cancel_schedule"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/campaigns/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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)"
}

POST Check campaign readiness

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Ask whether a draft campaign is ready to send, without sending it. This runs the same check the Send endpoint runs internally, so you can surface missing fields in your own UI before committing.

Read-only: it never changes the campaign.

Request body parameters

Field Type Required Description
action string Yes Must be check_readiness.

Response fields

Field Type Description
error string Empty on success.
ready boolean True when the campaign passes every content and recipient check.
message string Why it is not ready; an empty string when ready is true.
recipient_count integer Recipients currently on the campaign.

Possible message values: Campaign is not in draft status, No recipients added, Sender email is required, Sender name is required, Subject line is required, Email body is required, SMS sender ID is required, SMS message body is required, Unicode SMS message is too long (max 335 characters), SMS message is too long (max 765 characters), or one of the sender-email validation messages.

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.
Invalid request path 400 More than one path segment after /campaigns.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "check_readiness"
}'
import requests
import json

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

const body = JSON.stringify({
    "action": "check_readiness"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "action": "check_readiness"
}'
]);
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 = """
{
    "action": "check_readiness"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""action"": ""check_readiness""
}", 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(`{
    "action": "check_readiness"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "action": "check_readiness"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "ready": false,
  "message": "Sender email is required",
  "recipient_count": 240
}
{
  "error": "Campaign not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Duplicate campaign

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Copy a campaign into a new DRAFT. Works on a campaign in any status, so this is the normal way to re-run a campaign that has already sent.

Copied: title (prefixed Copy of), channels, all email and SMS content, attachments (both uploaded files and attachment_urls), and every recipient — individual addresses and numbers as well as contact lists. Not copied: the schedule, send history, unified media, and coupons.

Request body parameters

Field Type Required Description
action string Yes Must be duplicate.

Response fields

Field Type Description
error string Empty on success.
campaign_id string The new campaign's id.
title string The new campaign's title.
status string Always DRAFT.
recipient_count integer Recipients copied onto the new campaign.

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.
Invalid request path 400 More than one path segment after /campaigns.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "duplicate"
}'
import requests
import json

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

const body = JSON.stringify({
    "action": "duplicate"
});

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "action": "duplicate"
}'
]);
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 = """
{
    "action": "duplicate"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""action"": ""duplicate""
}", 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(`{
    "action": "duplicate"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/campaigns/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "action": "duplicate"
}'
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": "665f1a2b3c4d5e6f7a8b9c2e",
  "title": "Copy of July promo",
  "status": "DRAFT",
  "recipient_count": 240
}
{
  "error": "Campaign not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get campaign stats

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Delivery statistics for one campaign, without its recipient list. Use this to poll a sending campaign — Get campaign returns the same stats object but also embeds up to 100 recipient rows, so this is the cheaper poll.

Response fields

Field Type Description
error string Empty on success.
campaign_id string Campaign id.
status string DRAFT, SCHEDULED, SENDING, or SENT.
stats.type string sms, email, both, or none.
stats.email.total integer Emails generated for this campaign.
stats.email.queued integer Accepted, not yet sent.
stats.email.sent integer Handed to the mail provider.
stats.email.delivered integer Confirmed delivered.
stats.email.bounced integer Bounced.
stats.email.failed integer Failed, blocked, or complained.
stats.sms.total integer Messages generated for this campaign.
stats.sms.queued integer Queued, scheduled, or held for fraud review.
stats.sms.sent integer Handed to a carrier.
stats.sms.delivered integer Confirmed delivered.
stats.sms.failed integer Failed.
stats.has_fraud_hold boolean At least one message is held for fraud review.
stats.has_email_enquiry boolean At least one email is held pending an enquiry.

The email and sms objects are present only for the campaign's own channels.

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 request path 400 Unrecognised segment after the campaign id.

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/stats \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id/stats"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id/stats"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/stats");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/campaigns/:id/stats", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/stats")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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": "SENT",
  "stats": {
    "type": "sms",
    "sms": {
      "total": 240,
      "queued": 0,
      "sent": 12,
      "delivered": 226,
      "failed": 2
    },
    "has_fraud_hold": false,
    "has_email_enquiry": false
  }
}
{
  "error": "Campaign not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get campaign recipients

GET https://www.5centsms.com.au/api/v5/campaigns/:id/recipients?after=&limit=100

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Page through every recipient on a campaign, newest first. Get campaign embeds only the first 100; this endpoint returns all of them.

A recipient row is either an individual address/number or a whole contact list attached as a single row. A contact-list row therefore contributes contact_list_count to recipient_count while occupying one row here.

Query parameters

Field Type Required Description
after string No Cursor: the id of the last recipient on the previous page. Omit for the first page.
limit integer No Page size, 1–1000. Default 100.

Response fields

Field Type Description
error string Empty on success.
campaign_id string Campaign id.
count integer Rows on this page.
recipient_count integer Total recipients the campaign will send to, counting each contact list's members.
recipients[].id string Recipient row id — pass as after to page, or to Remove recipient.
recipients[].type string individual or contact_list.
recipients[].created integer When the row was added (unix).
recipients[].recipient_type string number or email (individual rows only).
recipients[].value string The address or number (individual rows only).
recipients[].contact_list_id string Contact list id (contact-list rows only).
recipients[].contact_list_name string Contact list name (contact-list rows only).
recipients[].contact_list_count integer Members in the list when it was attached (contact-list rows only).
next_page string Root-relative path to the next page. Present only when a full page was returned; absent on the last page.

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 after parameter 400 after is not a 24-char hex id.
Invalid limit parameter 400 limit is not numeric.
Invalid request path 400 Unrecognised segment after the campaign id.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
afterCursor: the id of the last recipient on the previous page.
limit100Page size, 1-1000. Default 100.

Path variables

VariableExampleDescription
idCampaign id (24-char hex).
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/campaigns/:id/recipients?after=&limit=100 \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id/recipients?after=&limit=100"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/campaigns/:id/recipients?after=&limit=100", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
req.end();
<?php
$ch = curl_init("https://www.5centsms.com.au/api/v5/campaigns/:id/recipients?after=&limit=100");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id/recipients?after=&limit=100"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/recipients?after=&limit=100");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/campaigns/:id/recipients?after=&limit=100", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/recipients?after=&limit=100")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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",
  "count": 2,
  "recipient_count": 242,
  "recipients": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c12",
      "type": "individual",
      "created": 1719792100,
      "recipient_type": "email",
      "value": "sam@example.com"
    },
    {
      "id": "665f1a2b3c4d5e6f7a8b9c11",
      "type": "contact_list",
      "created": 1719792000,
      "contact_list_id": "665f1a2b3c4d5e6f7a8b9c10",
      "contact_list_name": "Newsletter",
      "contact_list_count": 240
    }
  ],
  "next_page": "/api/v5/campaigns/665f1a2b3c4d5e6f7a8b9c0d/recipients?after=665f1a2b3c4d5e6f7a8b9c11&limit=2"
}
{
  "error": "",
  "campaign_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "count": 1,
  "recipient_count": 242,
  "recipients": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c09",
      "type": "individual",
      "created": 1719791900,
      "recipient_type": "number",
      "value": "61412345678"
    }
  ]
}
{
  "error": "Invalid after parameter"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET Get campaign merge fields

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

List the merge fields available to this campaign's content, derived from the contact lists attached to it.

Use a field in subject, email_body, email_text or sms_body as {{FieldName}} or [#FieldName#]. Each recipient's own value is substituted at send time, and a placeholder with no value for that contact is removed.

Merge fields only fill for contact-list recipients. Individually-added addresses and numbers carry no contact record, so every placeholder is stripped for them. The list is empty until at least one contact list is attached.

Response fields

Field Type Description
error string Empty on success.
fields array Field names: FirstName and LastName, then each custom field found on the attached lists. Empty when no contact list is attached.

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 request path 400 Unrecognised segment after the campaign id.

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/mergefields \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/campaigns/:id/mergefields"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/campaigns/:id/mergefields"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/mergefields");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/campaigns/:id/mergefields", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/mergefields")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "fields": [
    "FirstName",
    "LastName",
    "Company",
    "RenewalDate"
  ]
}
{
  "error": "Campaign not found"
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Sender IDs

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

List the sender IDs registered on your account, plus any a linked master account has chosen to share with you.

Response fields

Field Type Description
error string Empty on success.
senderids array Registered sender IDs, and any shared with this account by a linked master account.
senderids[].id string Sender ID record id.
senderids[].senderid string The sender ID value.
senderids[].status string Approval status: pending, acma_pending, approved, acma_approved, disallowed, or unverified.
senderids[].shared boolean true when this Sender ID belongs to a linked master account and was shared with you. Shared Sender IDs can be used to send but cannot be edited or deleted through this account's API key.
senderids[].acma_details_id string Id of the linked ACMA contact-details record. Pass it as acma_details_id on Create Sender ID to reuse the same details. Omitted when none is linked.
senderids[].acma_additional_details string Free-text notes supplied for ACMA registration. Omitted when empty.
senderids[].acma_evidence object Stored supporting evidence: filename, content_type, size (bytes) and uploaded_at (Unix timestamp). Omitted until the file has been stored, so it is also how you confirm an acma_evidence_url download completed.

The three acma_* fields describe an ACMA registration, which belongs to the account that owns the sender ID — they are omitted entirely on rows where shared is true.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/senderid \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/senderid"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/senderid", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/senderid"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/senderid", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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",
      "shared": false
    },
    {
      "id": "683554c596937cc4b90f5cf8",
      "senderid": "MASTERBRAND",
      "status": "acma_approved",
      "shared": true
    },
    {
      "id": "68a1f0c596937cc4b90f5d1a",
      "senderid": "ACMEPTY",
      "status": "acma_pending",
      "shared": false,
      "acma_details_id": "68a1f0c596937cc4b90f5d02",
      "acma_additional_details": "ACMEPTY is our registered trading name.",
      "acma_evidence": {
        "filename": "authorisation-letter.pdf",
        "content_type": "application/pdf",
        "size": 184320,
        "uploaded_at": 1755043200
      }
    }
  ]
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Sender ID

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Register a new sender ID for approval.

Text sender IDs must be registered with ACMA before they can send, so the registration material can be supplied with this call. Send the authorised contact details either as acma_details (the details themselves — we create the record and return its id) or as acma_details_id (an id from Create ACMA Contact Details, List ACMA Contact Details, or an earlier call to this endpoint) — one or the other, not both. acma_additional_details carries supporting information for the registration, and acma_evidence_url points at a supporting-evidence file — an authorisation letter, a trade-mark certificate, or whatever backs your claim to the sender ID — that we download and store against it.

Every ACMA and evidence field applies to text sender IDs only, and all are rejected when the sender ID already exists on the account — use the dashboard to change an existing one.

Request body parameters

Field Type Required Description
senderid string Yes The sender ID to register. Letters and digits only; max 11 characters.
acma_details object No Authorised contact details to create and link. Same fields as Create ACMA Contact Details: contact_name, contact_email and business_name are required within the object, contact_phone, abn, business_web, business_address, business_phone optional. Text sender IDs only. Cannot be combined with acma_details_id.
acma_details_id string No Id of an ACMA contact-details set already on this account, to link instead of creating one. Text sender IDs only. Cannot be combined with acma_details.
acma_additional_details string No Supporting information for the ACMA registration. Max 2000 characters. Text sender IDs only.
acma_evidence_url string No Public http/https URL of your supporting evidence (authorisation letter, trade-mark certificate, registration document). We check the URL's shape while handling the request and download it shortly afterwards in the background: 10-second timeout, up to 3 redirects, max 2 MB, must be a PDF, JPG, PNG, DOC or DOCX. Text sender IDs only.
acma_evidence_filename string No Filename to store the evidence under. Defaults to the last path segment of acma_evidence_url. Its extension decides whether the file type is accepted.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.
id string Sender ID record id. Returned for text sender IDs.
acma_details_id string Id of the contact-details set created or linked. Reuse it on your next sender ID. Present only when acma_details or acma_details_id was supplied.

Notes

  • Registration is not immediate: a new text sender ID is created pending and cannot send until it is reviewed, approved and registered with ACMA. This may take several business days. Poll List Sender IDs for the status.
  • Supplying acma_details, acma_additional_details or acma_evidence_url notifies our support team so the registration can be progressed.
  • Contact-details sets are reusable across sender IDs. Pass acma_details once, then reuse the returned acma_details_id, rather than sending the same details again.
  • Nothing is written until every field validates, so a rejected request leaves no sender ID and no contact-details record.

Errors

Error HTTP Cause
Missing Sender ID 400 senderid not supplied, or not a string.
Invalid new Sender ID 400 senderid is not 1-11 letters and digits.
ACMA registration details are only supported for text Sender IDs 400 acma_details, acma_details_id, acma_additional_details or acma_evidence_url supplied with a numeric sender ID.
You have already registered this Sender ID with ACMA and its contact details cannot be changed. Resubmit excluding contact details. Contact support for assistance. 400 Registration material supplied for a sender ID this account has already registered with ACMA. The contact details ACMA holds are permanent; resend the request without the acma_* fields to recreate the sender ID with the details it is already registered against.
Sender ID already exists on this account 400 Registration material supplied for a sender ID already on the account.
Supply either acma_details or acma_details_id, not both 400 Both were supplied.
Invalid ACMA contact details 400 acma_details is not an object, or one of its fields is not a string.
Contact Name, Contact Email and Business Name are required. 400 acma_details is missing one of the three required fields.
Invalid ACMA details ID 400 acma_details_id is not a 24-character hexadecimal id.
ACMA details not found 400 acma_details_id does not belong to this account.
Invalid Additional Details 400 acma_additional_details is not a string.
Additional Details is too long. Maximum 2000 characters. 400 acma_additional_details exceeds 2000 characters.
Invalid supporting evidence URL 400 acma_evidence_url is not a string.
Supporting evidence URL is not a valid URL. 400 acma_evidence_url is malformed.
Supporting evidence URL must be an http or https URL. 400 acma_evidence_url uses another scheme, or has no host.
Supporting evidence must be a PDF, JPG, PNG, DOC or DOCX file. 400 The filename extension is not an accepted type.
Sender ID not found. 400 The sender ID was removed while this request was in flight.
Unable to queue the supporting evidence 400 The sender ID and its details were saved, but the evidence download could not be scheduled. Upload the file in the dashboard; do not retry the create.
Unable to notify support for this Sender ID 400 The sender ID and its details were saved, but the support notification could not be queued. Do not retry the create; contact support.

Download problems — an unreachable URL, a file over 2 MB, a link that has expired — are not returned here, because the download happens after this response. We retry once and then email your account contact.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/senderid \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "senderid": "EXAMPLE",
    "acma_details": {
        "contact_name": "Jane Citizen",
        "contact_email": "jane@example.com",
        "contact_phone": "0400000000",
        "abn": "12345678901",
        "business_name": "Example Pty Ltd",
        "business_web": "https://www.example.com",
        "business_address": "1 Example Street, Sydney NSW 2000",
        "business_phone": "0290000000"
    },
    "acma_additional_details": "EXAMPLE is our registered trading name.",
    "acma_evidence_url": "https://files.example.com/authorisation-letter.pdf"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/senderid"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "senderid": "EXAMPLE",
    "acma_details": {
        "contact_name": "Jane Citizen",
        "contact_email": "jane@example.com",
        "contact_phone": "0400000000",
        "abn": "12345678901",
        "business_name": "Example Pty Ltd",
        "business_web": "https://www.example.com",
        "business_address": "1 Example Street, Sydney NSW 2000",
        "business_phone": "0290000000"
    },
    "acma_additional_details": "EXAMPLE is our registered trading name.",
    "acma_evidence_url": "https://files.example.com/authorisation-letter.pdf"
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "senderid": "EXAMPLE",
    "acma_details": {
        "contact_name": "Jane Citizen",
        "contact_email": "jane@example.com",
        "contact_phone": "0400000000",
        "abn": "12345678901",
        "business_name": "Example Pty Ltd",
        "business_web": "https://www.example.com",
        "business_address": "1 Example Street, Sydney NSW 2000",
        "business_phone": "0290000000"
    },
    "acma_additional_details": "EXAMPLE is our registered trading name.",
    "acma_evidence_url": "https://files.example.com/authorisation-letter.pdf"
});

const req = https.request("https://www.5centsms.com.au/api/v5/senderid", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "senderid": "EXAMPLE",
    "acma_details": {
        "contact_name": "Jane Citizen",
        "contact_email": "jane@example.com",
        "contact_phone": "0400000000",
        "abn": "12345678901",
        "business_name": "Example Pty Ltd",
        "business_web": "https://www.example.com",
        "business_address": "1 Example Street, Sydney NSW 2000",
        "business_phone": "0290000000"
    },
    "acma_additional_details": "EXAMPLE is our registered trading name.",
    "acma_evidence_url": "https://files.example.com/authorisation-letter.pdf"
}'
]);
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 = """
{
    "senderid": "EXAMPLE",
    "acma_details": {
        "contact_name": "Jane Citizen",
        "contact_email": "jane@example.com",
        "contact_phone": "0400000000",
        "abn": "12345678901",
        "business_name": "Example Pty Ltd",
        "business_web": "https://www.example.com",
        "business_address": "1 Example Street, Sydney NSW 2000",
        "business_phone": "0290000000"
    },
    "acma_additional_details": "EXAMPLE is our registered trading name.",
    "acma_evidence_url": "https://files.example.com/authorisation-letter.pdf"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/senderid"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""senderid"": ""EXAMPLE"",
    ""acma_details"": {
        ""contact_name"": ""Jane Citizen"",
        ""contact_email"": ""jane@example.com"",
        ""contact_phone"": ""0400000000"",
        ""abn"": ""12345678901"",
        ""business_name"": ""Example Pty Ltd"",
        ""business_web"": ""https://www.example.com"",
        ""business_address"": ""1 Example Street, Sydney NSW 2000"",
        ""business_phone"": ""0290000000""
    },
    ""acma_additional_details"": ""EXAMPLE is our registered trading name."",
    ""acma_evidence_url"": ""https://files.example.com/authorisation-letter.pdf""
}", 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(`{
    "senderid": "EXAMPLE",
    "acma_details": {
        "contact_name": "Jane Citizen",
        "contact_email": "jane@example.com",
        "contact_phone": "0400000000",
        "abn": "12345678901",
        "business_name": "Example Pty Ltd",
        "business_web": "https://www.example.com",
        "business_address": "1 Example Street, Sydney NSW 2000",
        "business_phone": "0290000000"
    },
    "acma_additional_details": "EXAMPLE is our registered trading name.",
    "acma_evidence_url": "https://files.example.com/authorisation-letter.pdf"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/senderid", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "senderid": "EXAMPLE",
    "acma_details": {
        "contact_name": "Jane Citizen",
        "contact_email": "jane@example.com",
        "contact_phone": "0400000000",
        "abn": "12345678901",
        "business_name": "Example Pty Ltd",
        "business_web": "https://www.example.com",
        "business_address": "1 Example Street, Sydney NSW 2000",
        "business_phone": "0290000000"
    },
    "acma_additional_details": "EXAMPLE is our registered trading name.",
    "acma_evidence_url": "https://files.example.com/authorisation-letter.pdf"
}'
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",
  "id": "683554c596937cc4b90f5cf7",
  "acma_details_id": "68a1f0c596937cc4b90f5d02"
}
{
  "error": "Supporting evidence must be a PDF, JPG, PNG, DOC or DOCX file."
}
{
  "error": "Failed (Invalid API ID or Key)"
}

DELETE Delete Sender ID

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Remove a sender ID from your account.

Response fields

Field Type Description
error string Empty on success.

Errors

Error HTTP Cause
Invalid Sender ID format 400 The id path segment is not a 24-character hexadecimal id.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/senderid/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/senderid/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/senderid/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/senderid/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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)"
}

POST Create ACMA Contact Details

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Create a set of ACMA authorised contact details on your account. ACMA requires these details for every text sender ID; the id returned here is what Create Sender ID takes as acma_details_id, and what List Sender IDs reports as senderids[].acma_details_id.

Sets are per-account and reusable — create one and link it to as many sender IDs as you like. Create Sender ID can also create a set inline from raw acma_details, which is the one-call alternative to this endpoint. Changing and deleting sets is done in the dashboard under Settings > Sender IDs.

Request body parameters

Field Type Required Description
contact_name string Yes Name of the authorised representative.
contact_email string Yes Email of the authorised representative. ACMA may email this address to confirm the registration. Stored lowercased.
business_name string Yes Registered business or organisation name.
contact_phone string No Phone number of the authorised representative.
abn string No ABN of the entity. Omit for non-ABN entities such as sole traders or individuals.
business_web string No Business website.
business_address string No Registered business address.
business_phone string No Business phone number.

Response fields

Field Type Description
error string Empty on success.
message string Confirmation message.
id string Contact-details record id. Pass this as acma_details_id on Create Sender ID.

Notes

  • Duplicate sets are allowed: each call creates a new record.
  • A set cannot be changed or removed once a sender ID linked to it has been submitted to or registered with ACMA.

Errors

Error HTTP Cause
Contact Name, Contact Email and Business Name are required. 400 One of the three required fields is missing or empty.
Invalid ACMA contact details 400 A supplied field is not a string.
Unable to notify support for these contact details 400 The details were saved, but the support notification could not be queued. Do not retry; contact support — find the set's id with List ACMA Contact Details.
Unsupported method. Please see our API Docs 400 DELETE on this path. Contact-details sets are changed and removed in the dashboard, not over the API.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/acmadetails \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_name": "Jane Citizen",
    "contact_email": "jane@example.com",
    "contact_phone": "0400000000",
    "abn": "12345678901",
    "business_name": "Example Pty Ltd",
    "business_web": "https://www.example.com",
    "business_address": "1 Example Street, Sydney NSW 2000",
    "business_phone": "0290000000"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/acmadetails"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "contact_name": "Jane Citizen",
    "contact_email": "jane@example.com",
    "contact_phone": "0400000000",
    "abn": "12345678901",
    "business_name": "Example Pty Ltd",
    "business_web": "https://www.example.com",
    "business_address": "1 Example Street, Sydney NSW 2000",
    "business_phone": "0290000000"
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "contact_name": "Jane Citizen",
    "contact_email": "jane@example.com",
    "contact_phone": "0400000000",
    "abn": "12345678901",
    "business_name": "Example Pty Ltd",
    "business_web": "https://www.example.com",
    "business_address": "1 Example Street, Sydney NSW 2000",
    "business_phone": "0290000000"
});

const req = https.request("https://www.5centsms.com.au/api/v5/acmadetails", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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/acmadetails");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "contact_name": "Jane Citizen",
    "contact_email": "jane@example.com",
    "contact_phone": "0400000000",
    "abn": "12345678901",
    "business_name": "Example Pty Ltd",
    "business_web": "https://www.example.com",
    "business_address": "1 Example Street, Sydney NSW 2000",
    "business_phone": "0290000000"
}'
]);
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 = """
{
    "contact_name": "Jane Citizen",
    "contact_email": "jane@example.com",
    "contact_phone": "0400000000",
    "abn": "12345678901",
    "business_name": "Example Pty Ltd",
    "business_web": "https://www.example.com",
    "business_address": "1 Example Street, Sydney NSW 2000",
    "business_phone": "0290000000"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/acmadetails"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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/acmadetails");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""contact_name"": ""Jane Citizen"",
    ""contact_email"": ""jane@example.com"",
    ""contact_phone"": ""0400000000"",
    ""abn"": ""12345678901"",
    ""business_name"": ""Example Pty Ltd"",
    ""business_web"": ""https://www.example.com"",
    ""business_address"": ""1 Example Street, Sydney NSW 2000"",
    ""business_phone"": ""0290000000""
}", 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(`{
    "contact_name": "Jane Citizen",
    "contact_email": "jane@example.com",
    "contact_phone": "0400000000",
    "abn": "12345678901",
    "business_name": "Example Pty Ltd",
    "business_web": "https://www.example.com",
    "business_address": "1 Example Street, Sydney NSW 2000",
    "business_phone": "0290000000"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/acmadetails", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/acmadetails")
request = Net::HTTP::Post.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "contact_name": "Jane Citizen",
    "contact_email": "jane@example.com",
    "contact_phone": "0400000000",
    "abn": "12345678901",
    "business_name": "Example Pty Ltd",
    "business_web": "https://www.example.com",
    "business_address": "1 Example Street, Sydney NSW 2000",
    "business_phone": "0290000000"
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "message": "ACMA contact details created",
  "id": "68a1f0c596937cc4b90f5d02"
}
{
  "error": "Contact Name, Contact Email and Business Name are required."
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List ACMA Contact Details

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

List the ACMA authorised contact-details sets on your account, oldest first. Use it to recover an acma_details_id you did not keep, or to check which details a sender ID is registered against.

Response fields

Field Type Description
error string Empty on success.
count integer Number of sets returned.
acma_details array The account's contact-details sets.
acma_details[].id string Record id. Pass as acma_details_id on Create Sender ID.
acma_details[].contact_name string Authorised representative's name.
acma_details[].contact_email string Authorised representative's email, lowercased.
acma_details[].contact_phone string Authorised representative's phone. Empty when not supplied.
acma_details[].abn string ABN. Empty for non-ABN entities.
acma_details[].business_name string Registered business or organisation name.
acma_details[].business_web string Business website. Empty when not supplied.
acma_details[].business_address string Registered business address. Empty when not supplied.
acma_details[].business_phone string Business phone. Empty when not supplied.
acma_details[].created integer Unix timestamp (seconds) the set was created. null on sets that predate this field.

Notes

  • An account with no sets returns count: 0 and an empty array, not an error.
  • To see which sender ID uses which set, read senderids[].acma_details_id from List Sender IDs.

Errors

None beyond authentication.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/acmadetails \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/acmadetails"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

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

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/acmadetails"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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/acmadetails");
request.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/acmadetails", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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/acmadetails")
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
Example Response
{
  "error": "",
  "count": 1,
  "acma_details": [
    {
      "id": "68a1f0c596937cc4b90f5d02",
      "contact_name": "Jane Citizen",
      "contact_email": "jane@example.com",
      "contact_phone": "0400000000",
      "abn": "12345678901",
      "business_name": "Example Pty Ltd",
      "business_web": "https://www.example.com",
      "business_address": "1 Example Street, Sydney NSW 2000",
      "business_phone": "0290000000",
      "created": 1755043200
    }
  ]
}
{
  "error": "",
  "count": 0,
  "acma_details": []
}
{
  "error": "Failed (Invalid API ID or Key)"
}

GET List Virtual Numbers

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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/virtualnumber"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/virtualnumber", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/virtualnumber"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/virtualnumber", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 Unified Messaging to be enabled for the account and provisions a Unified Virtual Number, which GET /virtualnumber reports as type: unified.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "AU",
    "type": "standard"
}'
import requests
import json

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

const body = JSON.stringify({
    "country": "AU",
    "type": "standard"
});

const req = https.request("https://www.5centsms.com.au/api/v5/virtualnumber", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "country": "AU",
    "type": "standard"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/virtualnumber"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "country": "AU",
    "type": "standard"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/virtualnumber", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/virtualnumber/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/virtualnumber/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/virtualnumber/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/virtualnumber/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/domain"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/domain", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/domain"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/domain", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 (Invalid Domain ID format) 400 The id path segment is not a 24-character hexadecimal id.
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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/domain/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/domain/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/domain/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/domain/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "subdomain": "email"
}'
import requests
import json

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

const body = JSON.stringify({
    "domain": "example.com",
    "subdomain": "email"
});

const req = https.request("https://api.dingomail.com.au/api/v5/domain", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "domain": "example.com",
    "subdomain": "email"
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/domain", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://api.dingomail.com.au/api/v5/mailboxes"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://api.dingomail.com.au/api/v5/mailboxes", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/mailboxes"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.dingomail.com.au/api/v5/mailboxes", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "newsletter"
}'
import requests
import json

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

const body = JSON.stringify({
    "name": "newsletter"
});

const req = https.request("https://api.dingomail.com.au/api/v5/mailboxes", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "name": "newsletter"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/mailboxes"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "name": "newsletter"
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/mailboxes", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
}'
import requests
import json

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

const body = JSON.stringify({
    "active": false
});

const req = https.request("https://api.dingomail.com.au/api/v5/mailboxes/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "active": false
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dingomail.com.au/api/v5/mailboxes/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "active": false
}`)
	req, _ := http.NewRequest("POST", "https://api.dingomail.com.au/api/v5/mailboxes/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Customers"
}'
import requests
import json

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

const body = JSON.stringify({
    "name": "VIP Customers"
});

const req = https.request("https://www.5centsms.com.au/api/v5/lists", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "name": "VIP Customers"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "name": "VIP Customers"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/lists", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/lists"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/lists", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/lists", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/lists/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/lists/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/lists/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/lists/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/lists/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/lists/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/lists/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "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, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "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: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/contacts", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/contacts", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/contacts/:id", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/contacts/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@example.com"
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "email": "jane.smith@example.com"
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "email": "jane.smith@example.com"
});

const req = https.request("https://www.5centsms.com.au/api/v5/contacts/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "email": "jane.smith@example.com"
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/contacts/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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

Send Authorization: Bearer <key-id>:<key-secret> on 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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/contacts/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/contacts/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/contacts/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/contacts/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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

Send Authorization: Bearer <key-id>:<key-secret> on 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, email_alerts, account_balance. Matches version 1 (legacy) webhooks only; a version 2 webhook stores no public type and is never matched by this filter.

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[].api_version integer 1 (legacy) or 2 (current).
webhooks[].type string|null One of sms_events, sms_inbound, sms_optout, email_inbound, email_events, email_alerts, account_balance for a version 1 webhook; null for a version 2 webhook, since it subscribes by individual event name rather than by type.
webhooks[].url string Destination URL the payload is POSTed to.
webhooks[].version integer Payload format version. Kept for backwards compatibility; always equal to api_version.
webhooks[].threshold integer|null Balance threshold; set only when the webhook fires on a low-balance condition, otherwise null.
webhooks[].events array Subscribed events; populated for email_events webhooks (subset of delivery, engagement, unsubscribe), for email_alerts webhooks (subset of bounce_rate, complaint_rate), and for every version 2 webhook (its full subscribed event list), otherwise [].
webhooks[].https_only boolean Version 2 only. Whether HTTPS and certificate verification are required. Always false for a version 1 webhook.
webhooks[].header_names array Version 2 only. Names of the custom headers sent with each delivery. Values are never returned. [] for a version 1 webhook, and for a version 2 webhook with no custom headers.
webhooks[].enabled boolean Whether the webhook is currently enabled.
webhooks[].auto_disabled boolean true when the webhook was disabled by repeated delivery failures. Only applies to version 2 webhooks.
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, email_alerts, account_balance 400 type filter is not an allowed value.

Request headers

HeaderValueDescription
Content-Typeapplication/json

Query parameters

ParameterExampleDescription
typeRestrict to one type. One of `sms_events`, `sms_inbound`, `sms_optout`, `email_inbound`, `email_events`, `email_alerts`, `account_balance`. Matches version 1 (legacy) webhooks only; a version 2 webhook stores no public `type` and is never matched by this filter.
Example Request
curl -X GET https://www.5centsms.com.au/api/v5/webhooks \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/webhooks"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("GET", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/webhooks", {
  method: "GET",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/webhooks"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://www.5centsms.com.au/api/v5/webhooks", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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",
      "api_version": 1,
      "type": "sms_events",
      "url": "https://example.com/dlr",
      "version": 1,
      "threshold": null,
      "events": [],
      "https_only": false,
      "header_names": [],
      "enabled": true,
      "auto_disabled": false
    },
    {
      "id": "7a1b2c3d4e5f60718293a4b5",
      "api_version": 1,
      "type": "email_events",
      "url": "https://example.com/email-events",
      "version": 1,
      "threshold": null,
      "events": [
        "delivery",
        "engagement"
      ],
      "https_only": false,
      "header_names": [],
      "enabled": true,
      "auto_disabled": false
    },
    {
      "id": "9f8e7d6c5b4a39281706f5e4",
      "api_version": 1,
      "type": "email_alerts",
      "url": "https://example.com/deliverability-alerts",
      "version": 1,
      "threshold": null,
      "events": [
        "bounce_rate",
        "complaint_rate"
      ],
      "https_only": false,
      "header_names": [],
      "enabled": true,
      "auto_disabled": false
    },
    {
      "id": "68be1f0c9a3b4c0012ab34cd",
      "api_version": 2,
      "type": null,
      "url": "https://example.com/hooks/sms",
      "version": 2,
      "threshold": null,
      "events": [
        "sms.delivered",
        "sms.failed"
      ],
      "https_only": true,
      "header_names": ["Authorization"],
      "enabled": true,
      "auto_disabled": false
    }
  ],
  "count": 4
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Create Webhook

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Create an outbound webhook configuration. Two contracts, selected by api_version. api_version: 1 (the default, "legacy") requires type and posts a URL-encoded body. api_version: 2 (the current contract) requires events and posts a signed JSON body; see the Webhooks page in your dashboard for the full payload contract - this is the management endpoint only.

Request body parameters

Field Type Required Description
api_version integer No 1 (default) or 2. Selects the webhook contract.
type string Yes for api_version 1 One of sms_events, sms_inbound, sms_optout, email_inbound, email_events, email_alerts, account_balance. Not accepted for api_version 2; returned as null.
url string Yes Destination URL. http:// (or https:// when https_only is true) is prepended if no scheme is given. The host is resolved and rejected if it does not resolve, or if any resolved address is private, loopback, link-local, carrier-grade NAT, multicast or reserved. Applies to both contracts.
threshold integer Conditional Required for type=account_balance (version 1), or when events contains account.balance_low (version 2): fires when the account balance is at or below this value (must be > 0). Ignored otherwise.
events array Conditional Version 1: required for type=email_events (subset of delivery, engagement, unsubscribe) or type=email_alerts (subset of bounce_rate, complaint_rate). Version 2: required, a non-empty subset of sms.sent, sms.delivered, sms.read, sms.failed, sms.cancelled, sms.inbound, sms.optout, email.delivered, email.bounced, email.complained, email.blocked, email.invalid, email.attachment_failed, email.too_many_recipients, email.blocked_dangerous_link, email.enquiry, email.opened, email.clicked, email.unsubscribed, email.inbound, email.alert.bounce_rate_warning, email.alert.bounce_rate_critical, email.alert.bounce_rate_cleared, email.alert.complaint_rate_warning, email.alert.complaint_rate_critical, email.alert.complaint_rate_cleared, account.balance_low. account.balance_low requires threshold. What each event delivers is documented on the Webhooks page in your dashboard. Duplicates are collapsed.
https_only boolean No Version 2 only. Defaults to true. Requires an https:// URL and verifies the certificate at delivery time.
headers object No Version 2 only. Up to 3 custom request headers, as an object of header name to value, sent with every delivery and every retry of this webhook - for example {"Authorization": "Bearer abc123"}. Names use the HTTP token character set (letters, digits and ! # % & ' * + . ^ _ ~ -, plus backtick and |), max 64 characters; values are printable ASCII, max 1024 characters. Headers the platform sets (Host, Content-Type, Content-Length, Transfer-Encoding, Connection, Expect, Accept-Encoding, User-Agent, X-Signature) and any name beginning X-Webhook- are rejected. Values are write-only: they are never returned by any endpoint and are redacted from your delivery logs.

Response fields

Field Type Description
error string Empty on success.
webhook object The created webhook (id, api_version, type, url, version, threshold, events, https_only, header_names, enabled, auto_disabled).
webhook.header_names array Version 2 only. The names of the custom headers stored for this webhook. Values are never returned.
secret string Version 2 only. The signing secret, returned once and never again.
message string Confirmation message.

Errors

Error HTTP Cause
Missing required field: type 400 api_version 1 (or omitted) with type not supplied.
Invalid type. Must be one of: sms_events, sms_inbound, sms_optout, email_inbound, email_events, email_alerts, 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.
Email alert webhooks require a non-empty events array (subset of: bounce_rate, complaint_rate) 400 type=email_alerts with events absent, not an array, or empty.
Invalid event. Must be one of: bounce_rate, complaint_rate 400 type=email_alerts with an events value outside the alert 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).
Invalid api_version. Must be 1 or 2 400 api_version present and neither 1 nor 2.
Version 2 webhooks require a non-empty events array 400 api_version 2 with events missing, not an array, or empty.
Invalid event. See the Webhooks documentation for the full list of event names. 400 An entry in events is not a recognised event name (version 2).
account.balance_low requires a numeric threshold greater than 0 400 account.balance_low subscribed (version 2) without a positive numeric threshold.
Webhooks require an https:// URL when HTTPS is required. 400 https_only is true and the URL is not https://.
Endpoint URI host could not be resolved. 400 The URL's host has no A or AAAA record. Applies to both contracts.
Endpoint URI resolves to an address we cannot send to. Use a publicly reachable host. 400 Any address the host resolves to is private, loopback, link-local, carrier-NAT, multicast or reserved. Applies to both contracts.
headers must be an object of header name to value 400 headers is present but is not an object.
Each custom header needs both a name and a value. 400 A header entry has an empty name or an empty value.
Custom header names are limited to 64 characters. 400 A header name is too long.
Custom header values are limited to 1024 characters. 400 A header value is too long.
Custom header names may contain letters, digits and ! # % & ' * + . ^ _ ` | ~ - only. 400 A header name is outside the HTTP token character set. The message carries a literal backtick and vertical bar, so this row is not code-formatted: a code span cannot render either character.
Custom header values may contain printable ASCII characters only. 400 A header value carries a control character, including CR or LF.
The header <name> is set by the platform and cannot be overridden. 400 A header name is one the platform sets, or begins X-Webhook-.
Custom header <name> is listed more than once. 400 Two header entries share a name, compared case-insensitively.
A webhook may carry at most 3 custom headers. 400 More than three header entries were supplied.
Invalid request parameters 400 A header name beginning $ - rejected by the API's request guard before this endpoint runs.

Example request body (version 2)

{
  "api_version": 2,
  "url": "https://example.com/hooks/sms",
  "events": ["sms.delivered", "sms.failed"],
  "https_only": true,
  "headers": {
    "Authorization": "Bearer abc123"
  }
}

Notes

  • Use api_version: 2 for new integrations. Version 1 is unchanged and stays available, so existing callers need no edit.
  • A webhook is created enabled and starts receiving events immediately.
  • url, type, events and headers cannot be changed after creation. Enabling and disabling is the only mutation; to change anything else, delete the webhook and create a replacement.
  • Duplicates are allowed. Several webhooks may point at the same URL, and several may subscribe to the same event.
  • Custom headers are sent as supplied, on every attempt. If your endpoint rejects a stale credential with a non-2xx status, that counts as a failed delivery and the webhook is auto-disabled after 5 consecutive failed deliveries like any other persistent failure.
  • Version 2 only: secret appears in this response and in no other response, ever. Store it before you discard the response body. A webhook whose secret is lost has to be deleted and recreated.
  • No event requires an account flag, and no webhook is billable. The email.alert.* events cover account-level bounce and complaint rates crossing a band; per-message email outcomes are the email.* events instead.
  • What your endpoint receives, how to verify X-Signature, and the retry and auto-disable schedule are on the Webhooks page in your dashboard. This endpoint reference deliberately does not repeat them.

Request headers

HeaderValueDescription
Content-Typeapplication/json
Example Request
curl -X POST https://www.5centsms.com.au/api/v5/webhooks \
  -H "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "type": "email_events",
    "url": "https://example.com/email-events",
    "events": [
        "delivery",
        "engagement"
    ]
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "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: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "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("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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": "",
  "webhook": {
    "id": "9f8e7d6c5b4a39281706f5e4",
    "type": "email_alerts",
    "url": "https://example.com/deliverability-alerts",
    "version": 1,
    "threshold": null,
    "events": [
      "bounce_rate",
      "complaint_rate"
    ],
    "enabled": true
  },
  "message": "Webhook created"
}
{
  "error": "",
  "webhook": {
    "id": "68be1f0c9a3b4c0012ab34cd",
    "api_version": 2,
    "type": null,
    "url": "https://example.com/hooks/sms",
    "version": 2,
    "threshold": null,
    "events": [
      "sms.delivered",
      "sms.failed"
    ],
    "https_only": true,
    "header_names": ["Authorization"],
    "enabled": true,
    "auto_disabled": false
  },
  "secret": "Zx7qWm2PdKfR9tHyBnLcVaJsEuQoXiMr4T3gY6wZ",
  "message": "Webhook created. Store the secret now - it is not returned again."
}
{
  "error": "Email webhooks require a non-empty events array (subset of: delivery, engagement, unsubscribe)"
}
{
  "error": "Invalid event. See the Webhooks documentation for the full list of event names."
}
{
  "error": "Failed (Invalid API ID or Key)"
}

POST Enable / Disable Webhook

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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Enable or disable an existing webhook by id. This is the only mutation on an existing webhook; url, type, events and headers are immutable (delete and recreate to change them).

Re-enabling a version 2 webhook that was auto-disabled also resets its consecutive failure count, so it gets a full run of deliveries before it can be auto-disabled again.

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 (id, api_version, type, url, version, threshold, events, https_only, header_names, enabled, auto_disabled).
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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
}'
import requests
import json

url = "https://www.5centsms.com.au/api/v5/webhooks/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
payload = json.loads('''{
    "enabled": false
}''')
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
const https = require("https");

const body = JSON.stringify({
    "enabled": false
});

const req = https.request("https://www.5centsms.com.au/api/v5/webhooks/:id", {
  method: "POST",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{
    "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 = """
{
    "enabled": false
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/webhooks/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
request.Content = new StringContent(@"{
    ""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(`{
    "enabled": false
}`)
	req, _ := http.NewRequest("POST", "https://www.5centsms.com.au/api/v5/webhooks/:id", body)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
request.body = '{
    "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",
    "api_version": 1,
    "type": "sms_events",
    "url": "https://example.com/dlr",
    "version": 1,
    "threshold": null,
    "events": [],
    "https_only": false,
    "header_names": [],
    "enabled": false,
    "auto_disabled": 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

Send Authorization: Bearer <key-id>:<key-secret> on every request.

Delete a webhook configuration by id.

Deleting a version 2 webhook destroys its signing secret. There is no way to recover it; a replacement webhook gets a new secret.

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 "Authorization: Bearer your-key-id:your-key-secret" \
  -H "Content-Type: application/json"
import requests
import json

url = "https://www.5centsms.com.au/api/v5/webhooks/:id"
headers = {"Authorization": "Bearer your-key-id:your-key-secret"}
response = requests.request("DELETE", url, headers=headers)
print(response.text)
const https = require("https");

const req = https.request("https://www.5centsms.com.au/api/v5/webhooks/:id", {
  method: "DELETE",
  headers: { "Authorization": "Bearer your-key-id:your-key-secret", "Content-Type": "application/json" }
}, res => {
  let data = "";
  res.on("data", chunk => data += chunk);
  res.on("end", () => console.log(data));
});
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 => ["Authorization: Bearer your-key-id:your-key-secret", "Content-Type: application/json"]
]);
echo curl_exec($ch);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.5centsms.com.au/api/v5/webhooks/:id"))
    .header("Authorization", "Bearer your-key-id:your-key-secret")
    .header("Content-Type", "application/json")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .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.Headers.Add("Authorization", "Bearer your-key-id:your-key-secret");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://www.5centsms.com.au/api/v5/webhooks/:id", nil)
	req.Header.Set("Authorization", "Bearer your-key-id:your-key-secret")
	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, "Authorization" => "Bearer your-key-id:your-key-secret", "Content-Type" => "application/json")
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)"
}