Hello there
\",\n \"Recipient\": \"jane@example.com\",\n \"ReplyTo\": \"support@example.com\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"messages\": [\n {\n \"Id\": \"683554c596937cc4b90f5cf7\",\n \"Status\": \"queued\",\n \"Recipients\": {\n \"To\": [\n \"jane@example.com\"\n ],\n \"CC\": [],\n \"TotalCount\": 1\n }\n }\n ]\n}" }, { "name": "200 OK (test mode)", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"messages\": [\n {\n \"Id\": \"6650f1a2b3c4d5e6f7a8b9c0\",\n \"Status\": \"test\",\n \"Recipients\": {\n \"To\": [\n \"someone@example.com\"\n ],\n \"CC\": [],\n \"TotalCount\": 1\n }\n }\n ]\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Invalid Sender Domain\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "List Emails", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/email", "host": [ "{{base_url_dingo}}" ], "path": [ "email" ], "query": [ { "key": "after", "value": "", "description": "24-hex cursor — the `id` of the last email on the previous page.", "disabled": true }, { "key": "limit", "value": "20", "description": "Page size, 1–100. Default 20.", "disabled": true } ] }, "description": "List sent emails, newest first.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `emails` | array | Emails this page. |\n| `emails[].id` | string | Email id. |\n| `emails[].status` | string | Email status. |\n| `emails[].from` | string | From address. |\n| `emails[].sender_name` | string | From display name. |\n| `emails[].to` | array | To recipients. |\n| `emails[].cc` | array | CC recipients. |\n| `emails[].subject` | string | Subject. |\n| `emails[].created_at` | integer | Epoch seconds created. |\n| `emails[].method` | string | Send method. |\n| `count` | integer | Emails on this page. |\n| `next_page` | string | Relative path for the next page — present only when `count >= limit`. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid after parameter` | 400 | `after` is not a valid 24-hex cursor. |\n| `Invalid limit parameter` | 400 | `limit` is outside 1–100. |\n\n#### Notes\n- `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.", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"emails\": [\n {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"status\": \"sent\",\n \"from\": \"news@mail.example.com\",\n \"sender_name\": \"Example\",\n \"to\": [\n \"jane@example.com\"\n ],\n \"cc\": [],\n \"subject\": \"Welcome\",\n \"created_at\": 1717000000,\n \"method\": \"api\"\n },\n {\n \"id\": \"683554c596937cc4b90f5cf5\",\n \"status\": \"sent\",\n \"from\": \"news@mail.example.com\",\n \"sender_name\": \"Example\",\n \"to\": [\n \"tom@example.com\"\n ],\n \"cc\": [],\n \"subject\": \"Your receipt\",\n \"created_at\": 1716999000,\n \"method\": \"api\"\n }\n ],\n \"count\": 2,\n \"next_page\": \"/api/v5/email?after=683554c596937cc4b90f5cf5&limit=2\"\n}" }, { "name": "200 OK (Last Page)", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"emails\": [\n {\n \"id\": \"683554c596937cc4b90f5cf1\",\n \"status\": \"sent\",\n \"from\": \"news@mail.example.com\",\n \"sender_name\": \"Example\",\n \"to\": [\n \"amy@example.com\"\n ],\n \"cc\": [],\n \"subject\": \"Order shipped\",\n \"created_at\": 1716998000,\n \"method\": \"api\"\n }\n ],\n \"count\": 1\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Get Email", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/email/:id", "host": [ "{{base_url_dingo}}" ], "path": [ "email", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Email id." } ] }, "description": "Fetch a single email, including its full text and HTML bodies.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `email` | object | id, status, from, sender_name, to, cc, subject, text, html, reply_to, created_at, method. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid email ID` | 400 | `id` is not a valid 24-hex id. |\n| `Email not found` | 400 | No such email, or not owned by this account. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"email\": {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"status\": \"sent\",\n \"from\": \"news@mail.example.com\",\n \"sender_name\": \"Example\",\n \"to\": [\n \"jane@example.com\"\n ],\n \"cc\": [],\n \"subject\": \"Welcome\",\n \"text\": \"Hello there\",\n \"html\": \"Hello there
\",\n \"reply_to\": \"support@example.com\",\n \"created_at\": 1717000000,\n \"method\": \"api\"\n }\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "List Inbound Emails", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/inboundemail", "host": [ "{{base_url_dingo}}" ], "path": [ "inboundemail" ], "query": [ { "key": "after", "value": "", "description": "24-hex cursor — the `id` of the last inbound email on the previous page.", "disabled": true }, { "key": "limit", "value": "20", "description": "Page size, 1–1000. Default 20.", "disabled": true }, { "key": "mailbox_address", "value": "", "description": "Optional. Restrict to inbound routed to this hosted mailbox address (lowercased). Omit for all inbound.", "disabled": true }, { "key": "include_archived", "value": "1", "description": "Optional. Set to 1 to include archived inbound email. Archived email is excluded by default.", "disabled": true } ] }, "description": "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.\n\n#### Query parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `after` | string | No | 24-hex cursor; `id` of the last row on the previous page. |\n| `limit` | integer | No | Page size 1–1000, default 20. |\n| `mailbox_address` | string | No | Restrict to one hosted mailbox address. |\n| `include_archived` | boolean | No | Set to `1` to include archived inbound email. Excluded by default. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `emails` | array | Inbound emails this page, newest first. |\n| `emails[].id` | string | Inbound email id. |\n| `emails[].from` | string | Sender address. |\n| `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. |\n| `emails[].to` | string | Raw To header the mail was delivered to. |\n| `emails[].subject` | string | Subject. |\n| `emails[].has_attachments` | boolean | True if the email has any attachment (inline or file). |\n| `emails[].archived` | boolean | True when the account has archived this email. Only ever `true` when `include_archived` is set. |\n| `emails[].mailbox_address` | string | Present only for hosted-mailbox-routed inbound. |\n| `emails[].created_at` | integer | Epoch seconds received. |\n| `count` | integer | Emails on this page. |\n| `next_page` | string | Relative path for the next page — present only when `count >= limit`. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid after parameter` | 400 | `after` is not a valid 24-hex cursor. |\n| `Invalid limit parameter` | 400 | `limit` is non-numeric. |\n| `Invalid mailbox_address parameter` | 400 | `mailbox_address` is not a string. |\n| `Unsupported method` | 400 | The collection route was called with DELETE, or with POST (POST is only valid on `/inboundemail/{id}`). |\n\n#### Notes\n- `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.\n- 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.", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"emails\": [\n {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"from\": \"jane@example.com\",\n \"from_name\": \"Jane Smith\",\n \"to\": \"support@mail.example.com\",\n \"subject\": \"Re: Welcome\",\n \"has_attachments\": false,\n \"archived\": false,\n \"created_at\": 1717000000\n },\n {\n \"id\": \"683554c596937cc4b90f5cf5\",\n \"from\": \"tom@example.com\",\n \"from_name\": \"\",\n \"to\": \"hello@mail.example.com\",\n \"subject\": \"Invoice attached\",\n \"has_attachments\": true,\n \"archived\": false,\n \"mailbox_address\": \"hello@mail.example.com\",\n \"created_at\": 1716999000\n }\n ],\n \"count\": 2,\n \"next_page\": \"/api/v5/inboundemail?after=683554c596937cc4b90f5cf5&limit=2\"\n}" }, { "name": "200 OK (Last Page)", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"emails\": [\n {\n \"id\": \"683554c596937cc4b90f5cf1\",\n \"from\": \"amy@example.com\",\n \"from_name\": \"Amy Jones\",\n \"to\": \"support@mail.example.com\",\n \"subject\": \"Question about my order\",\n \"has_attachments\": false,\n \"archived\": false,\n \"created_at\": 1716998000\n }\n ],\n \"count\": 1\n}" }, { "name": "200 OK (Including Archived)", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"emails\": [\n {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"from\": \"jane@example.com\",\n \"from_name\": \"Jane Smith\",\n \"to\": \"support@mail.example.com\",\n \"subject\": \"Re: Welcome\",\n \"has_attachments\": false,\n \"archived\": false,\n \"created_at\": 1717000000\n },\n {\n \"id\": \"683554c596937cc4b90f5cf5\",\n \"from\": \"tom@example.com\",\n \"from_name\": \"\",\n \"to\": \"hello@mail.example.com\",\n \"subject\": \"Invoice attached\",\n \"has_attachments\": true,\n \"archived\": true,\n \"mailbox_address\": \"hello@mail.example.com\",\n \"created_at\": 1716999000\n }\n ],\n \"count\": 2,\n \"next_page\": \"/api/v5/inboundemail?after=683554c596937cc4b90f5cf5&include_archived=1&limit=2\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Get Inbound Email", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/inboundemail/:id", "host": [ "{{base_url_dingo}}" ], "path": [ "inboundemail", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Inbound email id." } ] }, "description": "Fetch a single received email, including its full text and HTML bodies and attachment metadata. Scoped to the owning account.\n\n#### Path parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | string | Yes | 24-hex inbound email id. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `email.id` | string | Inbound email id. |\n| `email.from` | string | Sender address. |\n| `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. |\n| `email.to` | string | Raw To header. |\n| `email.subject` | string | Subject. |\n| `email.text` | string | Plain-text body. |\n| `email.html` | string | HTML body (inline `cid:` images already rewritten to S3 URLs). |\n| `email.attachments` | array | Attachment metadata. |\n| `email.attachments[].filename` | string | File name. |\n| `email.attachments[].content_type` | string | MIME type. |\n| `email.attachments[].size` | integer | Bytes. |\n| `email.attachments[].url` | string | Presigned S3 download URL, valid for 1 hour. |\n| `email.attachments[].content_id` | string | MIME Content-ID (inline images). |\n| `email.attachments[].is_inline` | boolean | True for embedded inline images. |\n| `email.mailbox_address` | string | Present only for hosted-mailbox-routed inbound. |\n| `email.mailbox_id` | string | Present only with `mailbox_address`. |\n| `email.archived` | boolean | True when the account has archived this email. Archived email stays fully readable through this endpoint. |\n| `email.archived_at` | integer | Epoch seconds of the archive request. Present only when `archived` is true. |\n| `email.created_at` | integer | Epoch seconds received. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid inbound email ID` | 400 | `id` is not a valid 24-hex id. |\n| `Inbound email not found` | 400 | No such inbound email, or not owned by this account. |\n| `Unsupported method` | 400 | The route was called with DELETE. POST on this route archives (see Archive Inbound Email). |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"email\": {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"from\": \"jane@example.com\",\n \"from_name\": \"Jane Smith\",\n \"to\": \"support@mail.example.com\",\n \"subject\": \"Re: Welcome\",\n \"text\": \"Thanks!\",\n \"html\": \"Thanks!
\",\n \"attachments\": [],\n \"archived\": false,\n \"created_at\": 1717000000\n }\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Archive Inbound Email", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/inboundemail/:id", "host": [ "{{base_url_dingo}}" ], "path": [ "inboundemail", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Inbound email id." } ] }, "description": "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}`.\n\n**Archiving is permanent.** There is no unarchive operation, on this endpoint or in the dashboard. Sending `archived: false` returns `Unarchiving is not supported`.\n\n#### Request body\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `key-id` | string | Yes | API key id (see intro auth). |\n| `key-secret` | string | Yes | API key secret (see intro auth). |\n| `archived` | boolean | Yes | Must be truthy (`true`, `1`, `\"true\"`). A falsy value is rejected - archiving cannot be reversed. |\n\n#### Path parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | string | Yes | 24-hex inbound email id. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `message` | string | `Inbound email archived`. |\n| `id` | string | The inbound email id acted on. |\n| `archived` | boolean | Always `true` on success. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid inbound email ID` | 400 | `id` is not a valid 24-hex id. |\n| `archived Required. Please see our API Docs` | 400 | The body has no `archived` field. |\n| `Unarchiving is not supported` | 400 | `archived` was sent as `false`, `0`, `\"false\"`, or `null`. |\n| `Inbound email not found` | 400 | No such inbound email, or not owned by this account. |\n| `Unsupported method` | 400 | POSTed to `/inboundemail` with no id. |\n\n#### Notes\n- Idempotent: re-archiving an already-archived email succeeds and returns the same body. It refreshes `archived_at` to the time of the latest request.\n- Archiving is free and does not touch the email quota.", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"key-id\": \"{{key_id}}\",\n \"key-secret\": \"{{key_secret}}\",\n \"archived\": true\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"message\": \"Inbound email archived\",\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"archived\": true\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Unarchiving is not supported\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] } ] }, { "name": "Account", "item": [ { "name": "Get Balance", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/balance", "host": [ "{{base_url_sms}}" ], "path": [ "balance" ] }, "description": "Get your account's credit balance and billing mode.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `balance` | object | Balance details. |\n| `balance.postpaid` | boolean | True if the account is postpaid. |\n| `balance.credits` | number | Available credits. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"balance\": {\n \"postpaid\": false,\n \"credits\": 1234.5\n }\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Pre-warm Send Queue", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/prewarm", "host": [ "{{base_url_sms}}" ], "path": [ "prewarm" ] }, "description": "Pre-warm the send queue ahead of a large campaign. Requires the QUEUE_PREWARM account flag; usable once per 60 minutes.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Account does not have queue pre-warming enabled` | 400 | QUEUE_PREWARM flag not set on the account. |\n| `Queue was already pre-warmed recently. Please wait {n} minutes before trying again.` | 400 | Pre-warmed within the last 60 minutes. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"message\": \"Queue pre-warming initiated.\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Account does not have queue pre-warming enabled\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] } ] }, { "name": "Logins", "item": [ { "name": "Create Login", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/logins", "host": [ "{{base_url_sms}}" ], "path": [ "logins" ] }, "description": "Create (or re-invite) a sub-login on your account.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | string | Yes | Login's display name. |\n| `email` | string | Yes | Login's email address. |\n| `role` | string | No | One of `admin`, `manager`, `sender`, `reporting`. Default `admin`. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `login_id` | string | The login's id. |\n| `is_new` | boolean | True if a new login was created. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Missing required field: name` | 400 | `name` not supplied. |\n| `Missing required field: email` | 400 | `email` not supplied. |\n| `Invalid email address` | 400 | `email` is malformed. |\n| `Invalid role. Must be one of: admin, manager, sender, reporting` | 400 | `role` is not an allowed value. |\n| `Login already exists on this account` | 400 | A login with that email already exists here. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"name\": \"Jane Smith\",\n \"email\": \"jane@example.com\",\n \"role\": \"admin\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"login_id\": \"683554c596937cc4b90f5cf7\",\n \"is_new\": true,\n \"message\": \"Login created\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Invalid role. Must be one of: admin, manager, sender, reporting\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "List Logins", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/logins", "host": [ "{{base_url_sms}}" ], "path": [ "logins" ] }, "description": "List all logins on your account.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `logins` | array | Logins on the account. |\n| `logins[].login_id` | string | Login id. |\n| `logins[].name` | string | Display name. |\n| `logins[].email` | string | Email address. |\n| `logins[].role` | string | Role. |\n| `count` | integer | Number of logins. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"logins\": [\n {\n \"login_id\": \"683554c596937cc4b90f5cf7\",\n \"name\": \"Jane Smith\",\n \"email\": \"jane@example.com\",\n \"role\": \"admin\"\n }\n ],\n \"count\": 1\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Change Login Role", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/logins/:login_id", "host": [ "{{base_url_sms}}" ], "path": [ "logins", ":login_id" ], "variable": [ { "key": "login_id", "value": "", "description": "Login id." } ] }, "description": "Change a login's role.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | string | Yes | Must be `change_role`. |\n| `role` | string | Yes | One of `admin`, `manager`, `sender`, `reporting`. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `login_id` | string | The login's id. |\n| `role` | string | The new role. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid login_id format` | 400 | `login_id` is not a valid id. |\n| `Missing required field: role` | 400 | `role` not supplied. |\n| `Invalid role. Must be one of: admin, manager, sender, reporting` | 400 | `role` is not an allowed value. |\n| `Login not found on this account` | 400 | No such login on this account. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"action\": \"change_role\",\n \"role\": \"manager\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"login_id\": \"683554c596937cc4b90f5cf7\",\n \"role\": \"manager\",\n \"message\": \"Role updated\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Delete Login", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/logins/:login_id", "host": [ "{{base_url_sms}}" ], "path": [ "logins", ":login_id" ], "variable": [ { "key": "login_id", "value": "", "description": "Login id." } ] }, "description": "Remove a login from your account.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `login_id` | string | The removed login's id. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid login_id format` | 400 | `login_id` is not a valid id. |\n| `Login not found on this account` | 400 | No such login on this account. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"login_id\": \"683554c596937cc4b90f5cf7\",\n \"message\": \"Login removed from account\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] } ] }, { "name": "Campaigns", "item": [ { "name": "Create campaign", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns" ] }, "description": "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.\n\nCampaigns are an account resource on the 5c SMS host (`{{base_url_sms}}`) for both channels.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `type` | string | No | `sms`, `email`, or `both`. Default `sms`. |\n| `title` | string | No | Campaign title. |\n| `sms_sender_id` | string | No | SMS sender ID or virtual number (SMS / both). |\n| `sms_body` | string | No | SMS message body (SMS / both). |\n| `sms_optout_enabled` | boolean | No | Append an opt-out link to the SMS. |\n| `sms_unicode_enabled` | boolean | No | Send the SMS as unicode. Requires the `UTF16` account feature. |\n| `sender_email` | string | No | From address; must be at one of your validated sending domains (email / both). |\n| `sender_name` | string | No | From name (email / both). |\n| `subject` | string | No | Email subject line (email / both). |\n| `email_body` | string | No | Email HTML body (email / both). |\n| `email_text` | string | No | Email plain-text body (email / both). |\n| `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). |\n| `emails` | string or array | No | Email addresses to add as individual recipients. Same format and cap as `numbers`. |\n| `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. |\n| `send` | boolean | No | If true, send the campaign immediately after it is built. |\n| `schedule` | integer or string | No | Unix timestamp or a `strtotime`-parseable string. Schedules the send for that time; supplying it implies `send`. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. Carries the send error if an inline `send`/`schedule` failed its gating (the campaign is still created). |\n| `campaign_id` | string | The new campaign's id. |\n| `status` | string | `DRAFT`, or `SENDING` / `SCHEDULED` if sent inline. |\n| `recipient_count` | integer | Recipients currently on the campaign. |\n| `recipients_added` | integer | Individual recipients added (present only when inline recipients were supplied). |\n| `recipient_errors` | array | Per-recipient errors for skipped individuals (present only when inline recipients were supplied). |\n| `send` | object | The send result (present only when `send`/`schedule` was requested): `error`, `campaign_id`, `status`, `message`. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign type` | 400 | `type` is not `sms`, `email`, or `both`. |\n| `Unicode requires the UTF16 feature on your account` | 400 | `sms_unicode_enabled` set without the `UTF16` account feature. |\n\n> **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.", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"type\": \"sms\",\n \"title\": \"July promo\",\n \"sms_sender_id\": \"EXAMPLE\",\n \"sms_body\": \"Hello from Acme!\",\n \"sms_optout_enabled\": true,\n \"contact_list_ids\": [\"683554c596937cc4b90f5cf7\"],\n \"send\": false\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"campaign_id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n \"status\": \"DRAFT\",\n \"recipient_count\": 240,\n \"recipients_added\": 0,\n \"recipient_errors\": []\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Invalid campaign type\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "List campaigns", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns" ] }, "description": "List your account's campaigns, most-recent-first. Returns up to the 200 most recent campaigns; older campaigns are purged 365 days after creation.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `campaigns` | array | Campaigns, newest first. |\n| `campaigns[].campaign_id` | string | Campaign id. |\n| `campaigns[].title` | string | Campaign title. |\n| `campaigns[].status` | string | `DRAFT`, `SCHEDULED`, `SENDING`, or `SENT`. |\n| `campaigns[].type` | array | Channels: any of `sms`, `email`. |\n| `campaigns[].recipient_count` | integer | Recipients on the campaign. |\n| `campaigns[].schedule` | integer | Scheduled send time (unix), or null. |\n| `count` | integer | Number of campaigns returned. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"campaigns\": [\n {\n \"campaign_id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n \"title\": \"July promo\",\n \"status\": \"SENT\",\n \"type\": [\"sms\"],\n \"recipient_count\": 240,\n \"schedule\": null\n }\n ],\n \"count\": 1\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Get campaign", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "Fetch one campaign: its settings, recipients, and combined SMS/email delivery stats.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `campaign_id` | string | Campaign id. |\n| `title` | string | Campaign title. |\n| `status` | string | `DRAFT`, `SCHEDULED`, `SENDING`, or `SENT`. |\n| `type` | array | Channels: any of `sms`, `email`. |\n| `recipient_count` | integer | Recipients on the campaign. |\n| `schedule` | integer | Scheduled send time (unix), or null. |\n| `sms` | object | SMS settings (present for `sms`/`both`): `sender_id`, `body`, `optout_enabled`, `unicode_enabled`. |\n| `email` | object | Email settings (present for `email`/`both`): `sender_email`, `sender_name`, `subject`, `has_body`. |\n| `recipients` | array | Recipient rows: `id`, `type` (`individual`/`contact_list`), and either `recipient_type`+`value` or `contact_list_id`+`contact_list_name`+`contact_list_count`, plus `created`. |\n| `stats` | object | Delivery stats: `type` (`sms`/`email`/`both`/`none`); `sms` and/or `email` count objects. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"campaign_id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n \"title\": \"July promo\",\n \"status\": \"SENT\",\n \"type\": [\"sms\"],\n \"recipient_count\": 240,\n \"schedule\": null,\n \"sms\": {\n \"sender_id\": \"EXAMPLE\",\n \"body\": \"Hello from Acme!\",\n \"optout_enabled\": true,\n \"unicode_enabled\": false\n },\n \"recipients\": [\n {\n \"id\": \"665f1a2b3c4d5e6f7a8b9c11\",\n \"type\": \"contact_list\",\n \"contact_list_id\": \"683554c596937cc4b90f5cf7\",\n \"contact_list_name\": \"VIP\",\n \"contact_list_count\": 240,\n \"created\": 1721700000\n }\n ],\n \"stats\": {\n \"type\": \"sms\",\n \"sms\": { \"total\": 240, \"queued\": 0, \"sent\": 40, \"delivered\": 195, \"failed\": 5 }\n }\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Campaign not found\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Update campaign", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "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.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | string | Yes | Must be `update`. |\n| `type` | string | No | `sms`, `email`, or `both`. |\n| `title` | string | No | Campaign title. |\n| `sms_sender_id` | string | No | SMS sender ID or virtual number. |\n| `sms_body` | string | No | SMS message body. |\n| `sms_optout_enabled` | boolean | No | Append an opt-out link to the SMS. |\n| `sms_unicode_enabled` | boolean | No | Send as unicode. Requires the `UTF16` account feature. |\n| `sender_email` | string | No | From address; must be at one of your validated domains. |\n| `sender_name` | string | No | From name. |\n| `subject` | string | No | Email subject line. |\n| `email_body` | string | No | Email HTML body. |\n| `email_text` | string | No | Email plain-text body. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `campaign_id` | string | Campaign id. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |\n| `Invalid or missing action` | 400 | `action` is absent or not a supported action. |\n| `Cannot edit campaign - not in draft status` | 400 | The campaign is not in `DRAFT`. |\n| `Invalid campaign type` | 400 | `type` is not `sms`, `email`, or `both`. |\n| `Unicode requires the UTF16 feature on your account` | 400 | `sms_unicode_enabled` set without the `UTF16` account feature. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"action\": \"update\",\n \"title\": \"July promo (final)\",\n \"sms_body\": \"Hello from Acme! Reply STOP to opt out.\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"campaign_id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n \"message\": \"Campaign updated\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Cannot edit campaign - not in draft status\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Add recipients", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "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).\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | string | Yes | Must be `add_recipients`. |\n| `numbers` | string or array | No | Phone numbers. Array, or comma/newline-delimited string. |\n| `emails` | string or array | No | Email addresses. Same format as `numbers`. |\n| `contact_list_ids` | string or array | No | Contact list ids (24-char hex) you own. |\n\nAt least one of `numbers`, `emails`, or `contact_list_ids` must be non-empty.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `added` | integer | Individual recipients successfully added. |\n| `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`. |\n| `recipient_count` | integer | Total recipients on the campaign after the call. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |\n| `Invalid or missing action` | 400 | `action` is absent or not a supported action. |\n| `Cannot modify recipients - not in draft status` | 400 | The campaign is not in `DRAFT`. |\n| `No recipients provided` | 400 | None of `numbers`/`emails`/`contact_list_ids` supplied. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"action\": \"add_recipients\",\n \"numbers\": [\"0404123123\", \"0404123124\"],\n \"contact_list_ids\": [\"683554c596937cc4b90f5cf7\"]\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"added\": 2,\n \"errors\": [],\n \"recipient_count\": 242\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"No recipients provided\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Remove recipient", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "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.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | string | Yes | Must be `remove_recipient`. |\n| `recipient_id` | string | Yes | The recipient row id (24-char hex). |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `recipient_count` | integer | Total recipients remaining. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |\n| `Invalid or missing action` | 400 | `action` is absent or not a supported action. |\n| `Cannot modify recipients - not in draft status` | 400 | The campaign is not in `DRAFT`. |\n| `recipient_id is required` | 400 | `recipient_id` missing or not a valid id. |\n| `Recipient not found` | 400 | No such recipient row on this campaign. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"action\": \"remove_recipient\",\n \"recipient_id\": \"665f1a2b3c4d5e6f7a8b9c11\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"recipient_count\": 2\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"recipient_id is required\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Clear recipients", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "Remove all recipients from a draft campaign. Only campaigns in `DRAFT` status can be modified.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | string | Yes | Must be `clear_recipients`. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `recipient_count` | integer | Always `0` on success. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |\n| `Invalid or missing action` | 400 | `action` is absent or not a supported action. |\n| `Cannot modify recipients - not in draft status` | 400 | The campaign is not in `DRAFT`. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"action\": \"clear_recipients\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"recipient_count\": 0\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Send / schedule campaign", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "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.\n\nSend-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.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | string | Yes | Must be `send`. |\n| `schedule` | integer or string | No | Unix timestamp or a `strtotime`-parseable string, in the future. Omit to send immediately. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `campaign_id` | string | Campaign id. |\n| `status` | string | `SENDING` (immediate) or `SCHEDULED`. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |\n| `Invalid or missing action` | 400 | `action` is absent or not a supported action. |\n| `Campaign is not in draft status` | 400 | The campaign is not in `DRAFT`. |\n| `You need an active email plan to send email campaigns` | 400 | Email campaign with no email quota. |\n| `You need a verified domain to send email campaigns` | 400 | Email campaign with no verified sending domain. |\n| `You need SMS credits or a postpaid account to send SMS campaigns` | 400 | SMS campaign with zero balance and not postpaid. |\n| `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. |\n| `Scheduled time must be in the future` | 400 | `schedule` did not parse or is not in the future. |\n| `No recipients added` | 400 | Readiness: campaign has no recipients. |\n| `SMS sender ID is required` | 400 | Readiness: SMS channel missing sender ID. |\n| `SMS message body is required` | 400 | Readiness: SMS channel missing body. |\n| `SMS message is too long (max 760 characters)` | 400 | Readiness: SMS body exceeds the GSM length limit. |\n| `Unicode SMS message is too long (max 335 characters)` | 400 | Readiness: unicode SMS body exceeds the unicode length limit. |\n| `Sender email is required` | 400 | Readiness: email channel missing sender email. |\n| `Sender name is required` | 400 | Readiness: email channel missing sender name. |\n| `Subject line is required` | 400 | Readiness: email channel missing subject. |\n| `Email body is required` | 400 | Readiness: email channel missing body. |\n| `Campaign is already sending` | 400 | Send already in progress. |\n| `Campaign is already scheduled` | 400 | A schedule is already set. |\n| `Campaign has already been sent` | 400 | The campaign was already sent. |\n| `Failed to start campaign` | 400 | The send could not be started (defensive fallback). |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"action\": \"send\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"campaign_id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n \"status\": \"SENDING\",\n \"message\": \"Campaign started\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"You need a verified domain to send email campaigns\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Cancel schedule", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "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.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `action` | string | Yes | Must be `cancel_schedule`. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `campaign_id` | string | Campaign id. |\n| `status` | string | `DRAFT`. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |\n| `Invalid or missing action` | 400 | `action` is absent or not a supported action. |\n| `Campaign is not scheduled` | 400 | The campaign is not in `SCHEDULED`. |\n| `Cannot cancel - less than 30 minutes until scheduled send` | 400 | Too close to the scheduled send time. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"action\": \"cancel_schedule\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"campaign_id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n \"status\": \"DRAFT\",\n \"message\": \"Schedule cancelled\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Cannot cancel - less than 30 minutes until scheduled send\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Delete campaign", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/campaigns/:id", "host": [ "{{base_url_sms}}" ], "path": [ "campaigns", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Campaign id (24-char hex)." } ] }, "description": "Delete a campaign and its recipients. Only draft campaigns can be deleted — campaigns that are sending, scheduled, or already sent cannot be removed.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `campaign_id` | string | The deleted campaign's id. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid campaign_id format` | 400 | The path id is not a 24-char hex id. |\n| `Campaign not found` | 400 | No such campaign on this account. |\n| `Cannot delete campaign` | 400 | The campaign is sending, scheduled, or sent. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"campaign_id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n \"message\": \"Campaign deleted\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Cannot delete campaign\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] } ] }, { "name": "Sender IDs", "item": [ { "name": "List Sender IDs", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/senderid", "host": [ "{{base_url_sms}}" ], "path": [ "senderid" ] }, "description": "List the sender IDs registered on your account, plus any a linked master account has chosen to share with you.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `senderids` | array | Registered sender IDs, and any shared with this account by a linked master account. |\n| `senderids[].id` | string | Sender ID record id. |\n| `senderids[].senderid` | string | The sender ID value. |\n| `senderids[].status` | string | Approval status: `pending`, `acma_pending`, `approved`, `acma_approved`, `disallowed`, or `unverified`. |\n| `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. |\n| `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. |\n| `senderids[].acma_additional_details` | string | Free-text notes supplied for ACMA registration. Omitted when empty. |\n| `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. |\n\nThe 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`.", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"senderids\": [\n {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"senderid\": \"EXAMPLE\",\n \"status\": \"approved\",\n \"shared\": false\n },\n {\n \"id\": \"683554c596937cc4b90f5cf8\",\n \"senderid\": \"MASTERBRAND\",\n \"status\": \"acma_approved\",\n \"shared\": true\n },\n {\n \"id\": \"68a1f0c596937cc4b90f5d1a\",\n \"senderid\": \"ACMEPTY\",\n \"status\": \"acma_pending\",\n \"shared\": false,\n \"acma_details_id\": \"68a1f0c596937cc4b90f5d02\",\n \"acma_additional_details\": \"ACMEPTY is our registered trading name.\",\n \"acma_evidence\": {\n \"filename\": \"authorisation-letter.pdf\",\n \"content_type\": \"application/pdf\",\n \"size\": 184320,\n \"uploaded_at\": 1755043200\n }\n }\n ]\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Create Sender ID", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/senderid", "host": [ "{{base_url_sms}}" ], "path": [ "senderid" ] }, "description": "Register a new sender ID for approval.\n\nText 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.\n\nEvery 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.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `senderid` | string | Yes | The sender ID to register. Letters and digits only; max 11 characters. |\n| `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`. |\n| `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`. |\n| `acma_additional_details` | string | No | Supporting information for the ACMA registration. Max 2000 characters. Text sender IDs only. |\n| `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. |\n| `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. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `message` | string | Confirmation message. |\n| `id` | string | Sender ID record id. Returned for text sender IDs. |\n| `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. |\n\n#### Notes\n- 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.\n- Supplying `acma_details`, `acma_additional_details` or `acma_evidence_url` notifies our support team so the registration can be progressed.\n- 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.\n- Nothing is written until every field validates, so a rejected request leaves no sender ID and no contact-details record.\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Missing Sender ID` | 400 | `senderid` not supplied, or not a string. |\n| `Invalid new Sender ID` | 400 | `senderid` is not 1-11 letters and digits. |\n| `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. |\n| `Sender ID already exists on this account` | 400 | Registration material supplied for a sender ID already on the account. |\n| `Supply either acma_details or acma_details_id, not both` | 400 | Both were supplied. |\n| `Invalid ACMA contact details` | 400 | `acma_details` is not an object, or one of its fields is not a string. |\n| `Contact Name, Contact Email and Business Name are required.` | 400 | `acma_details` is missing one of the three required fields. |\n| `Invalid ACMA details ID` | 400 | `acma_details_id` is not a 24-character hexadecimal id. |\n| `ACMA details not found` | 400 | `acma_details_id` does not belong to this account. |\n| `Invalid Additional Details` | 400 | `acma_additional_details` is not a string. |\n| `Additional Details is too long. Maximum 2000 characters.` | 400 | `acma_additional_details` exceeds 2000 characters. |\n| `Invalid supporting evidence URL` | 400 | `acma_evidence_url` is not a string. |\n| `Supporting evidence URL is not a valid URL.` | 400 | `acma_evidence_url` is malformed. |\n| `Supporting evidence URL must be an http or https URL.` | 400 | `acma_evidence_url` uses another scheme, or has no host. |\n| `Supporting evidence must be a PDF, JPG, PNG, DOC or DOCX file.` | 400 | The filename extension is not an accepted type. |\n| `Sender ID not found.` | 400 | The sender ID was removed while this request was in flight. |\n| `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. |\n| `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. |\n\nDownload 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.\n", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"senderid\": \"EXAMPLE\",\n \"acma_details\": {\n \"contact_name\": \"Jane Citizen\",\n \"contact_email\": \"jane@example.com\",\n \"contact_phone\": \"0400000000\",\n \"abn\": \"12345678901\",\n \"business_name\": \"Example Pty Ltd\",\n \"business_web\": \"https://www.example.com\",\n \"business_address\": \"1 Example Street, Sydney NSW 2000\",\n \"business_phone\": \"0290000000\"\n },\n \"acma_additional_details\": \"EXAMPLE is our registered trading name.\",\n \"acma_evidence_url\": \"https://files.example.com/authorisation-letter.pdf\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"message\": \"Sender ID created\",\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"acma_details_id\": \"68a1f0c596937cc4b90f5d02\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Supporting evidence must be a PDF, JPG, PNG, DOC or DOCX file.\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Delete Sender ID", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/senderid/:id", "host": [ "{{base_url_sms}}" ], "path": [ "senderid", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Sender ID record id." } ] }, "description": "Remove a sender ID from your account.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid Sender ID format` | 400 | The `id` path segment is not a 24-character hexadecimal id. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Create ACMA Contact Details", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/acmadetails", "host": [ "{{base_url_sms}}" ], "path": [ "acmadetails" ] }, "description": "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`.\n\nSets 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.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `contact_name` | string | Yes | Name of the authorised representative. |\n| `contact_email` | string | Yes | Email of the authorised representative. ACMA may email this address to confirm the registration. Stored lowercased. |\n| `business_name` | string | Yes | Registered business or organisation name. |\n| `contact_phone` | string | No | Phone number of the authorised representative. |\n| `abn` | string | No | ABN of the entity. Omit for non-ABN entities such as sole traders or individuals. |\n| `business_web` | string | No | Business website. |\n| `business_address` | string | No | Registered business address. |\n| `business_phone` | string | No | Business phone number. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `message` | string | Confirmation message. |\n| `id` | string | Contact-details record id. Pass this as `acma_details_id` on **Create Sender ID**. |\n\n#### Notes\n- Duplicate sets are allowed: each call creates a new record.\n- A set cannot be changed or removed once a sender ID linked to it has been submitted to or registered with ACMA.\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Contact Name, Contact Email and Business Name are required.` | 400 | One of the three required fields is missing or empty. |\n| `Invalid ACMA contact details` | 400 | A supplied field is not a string. |\n| `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**. |\n| `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. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"contact_name\": \"Jane Citizen\",\n \"contact_email\": \"jane@example.com\",\n \"contact_phone\": \"0400000000\",\n \"abn\": \"12345678901\",\n \"business_name\": \"Example Pty Ltd\",\n \"business_web\": \"https://www.example.com\",\n \"business_address\": \"1 Example Street, Sydney NSW 2000\",\n \"business_phone\": \"0290000000\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"message\": \"ACMA contact details created\",\n \"id\": \"68a1f0c596937cc4b90f5d02\"\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Contact Name, Contact Email and Business Name are required.\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "List ACMA Contact Details", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/acmadetails", "host": [ "{{base_url_sms}}" ], "path": [ "acmadetails" ] }, "description": "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.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `count` | integer | Number of sets returned. |\n| `acma_details` | array | The account's contact-details sets. |\n| `acma_details[].id` | string | Record id. Pass as `acma_details_id` on **Create Sender ID**. |\n| `acma_details[].contact_name` | string | Authorised representative's name. |\n| `acma_details[].contact_email` | string | Authorised representative's email, lowercased. |\n| `acma_details[].contact_phone` | string | Authorised representative's phone. Empty when not supplied. |\n| `acma_details[].abn` | string | ABN. Empty for non-ABN entities. |\n| `acma_details[].business_name` | string | Registered business or organisation name. |\n| `acma_details[].business_web` | string | Business website. Empty when not supplied. |\n| `acma_details[].business_address` | string | Registered business address. Empty when not supplied. |\n| `acma_details[].business_phone` | string | Business phone. Empty when not supplied. |\n| `acma_details[].created` | integer | Unix timestamp (seconds) the set was created. `null` on sets that predate this field. |\n\n#### Notes\n- An account with no sets returns `count: 0` and an empty array, not an error.\n- To see which sender ID uses which set, read `senderids[].acma_details_id` from **List Sender IDs**.\n\n#### Errors\nNone beyond authentication.", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"count\": 1,\n \"acma_details\": [\n {\n \"id\": \"68a1f0c596937cc4b90f5d02\",\n \"contact_name\": \"Jane Citizen\",\n \"contact_email\": \"jane@example.com\",\n \"contact_phone\": \"0400000000\",\n \"abn\": \"12345678901\",\n \"business_name\": \"Example Pty Ltd\",\n \"business_web\": \"https://www.example.com\",\n \"business_address\": \"1 Example Street, Sydney NSW 2000\",\n \"business_phone\": \"0290000000\",\n \"created\": 1755043200\n }\n ]\n}" }, { "name": "200 OK (no sets)", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"count\": 0,\n \"acma_details\": []\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] } ] }, { "name": "Virtual Numbers", "item": [ { "name": "List Virtual Numbers", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/virtualnumber", "host": [ "{{base_url_sms}}" ], "path": [ "virtualnumber" ] }, "description": "List the virtual numbers on your account.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `virtualnumbers` | array | Virtual numbers. |\n| `virtualnumbers[].id` | string | Virtual number record id. |\n| `virtualnumbers[].number` | string | Number in international format. |\n| `virtualnumbers[].number_formatted` | string | Human-formatted number. |\n| `virtualnumbers[].country` | string | Country code. |\n| `virtualnumbers[].type` | string | `standard` or `unified`. |\n| `count` | integer | Number of virtual numbers. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"virtualnumbers\": [\n {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"number\": \"61400000000\",\n \"number_formatted\": \"0400 000 000\",\n \"country\": \"AU\",\n \"type\": \"standard\"\n }\n ],\n \"count\": 1\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Purchase Virtual Number", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/virtualnumber", "host": [ "{{base_url_sms}}" ], "path": [ "virtualnumber" ] }, "description": "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.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `country` | string | Yes | Only `AU` is supported for API purchases. |\n| `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`. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `message` | string | Confirmation message. |\n| `virtualnumber` | object | `{id, number, number_formatted, country}`. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Missing required parameter: country` | 400 | `country` not supplied. |\n| `Invalid country. Currently only AU is supported for API requests.` | 400 | `country` is not `AU`. |\n| `Invalid type. Must be \"standard\" or \"unified\".` | 400 | `type` is not an allowed value. |\n| `Your account is not enabled for Unified Mobile Numbers. Please contact us.` | 400 | `type: unified` without the ENABLE_UNIFIED flag. |\n| `Your account is currently on hold. Please contact us to purchase a virtual number.` | 400 | Account is on hold. |\n| `Maximum virtual numbers reached. Contact us to request increaed quota.` | 400 | Number limit reached (default 2). |\n| `No payment method on file. Please add a payment method in the dashboard.` | 400 | No card on file. |\n| `Invalid subscription plan` | 400 | Subscription plan could not be resolved. |\n| `Your payment was declined by your bank.` | 400 | Card charge declined. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"country\": \"AU\",\n \"type\": \"standard\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"message\": \"Virtual number purchased\",\n \"virtualnumber\": {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"number\": \"61400000000\",\n \"number_formatted\": \"0400 000 000\",\n \"country\": \"AU\"\n }\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Invalid country. Currently only AU is supported for API requests.\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Delete Virtual Number", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_sms}}/virtualnumber/:id", "host": [ "{{base_url_sms}}" ], "path": [ "virtualnumber", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Virtual number record id." } ] }, "description": "Release a virtual number and cancel its subscription.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `message` | string | Confirmation message. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Invalid virtual number ID format` | 400 | `id` is not a valid id. |\n| `Virtual number not found` | 400 | No such virtual number. |\n| `Unauthorized - you do not own this virtual number` | 400 | Number not owned by this account. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"message\": \"Virtual number released\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] } ] }, { "name": "Email Domains", "item": [ { "name": "List Domains", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/domain", "host": [ "{{base_url_dingo}}" ], "path": [ "domain" ] }, "description": "List the email domains registered on your account.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `domains` | array | Registered domains. |\n| `domains[].id` | string | Domain record id. |\n| `domains[].domain` | string | Domain name. |\n| `domains[].subdomain` | string | Sending subdomain. |\n| `domains[].status` | string | Verification status. |\n| `domains[].dkim_names` | array | DKIM record names. |\n| `domains[].verification` | string | SES verification state. |\n| `count` | integer | Number of domains. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"domains\": [\n {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"domain\": \"example.com\",\n \"subdomain\": \"email\",\n \"status\": \"verified\",\n \"dkim_names\": [\n \"k1._domainkey\"\n ],\n \"verification\": \"verified\"\n }\n ],\n \"count\": 1\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Get Domain", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/domain/:id", "host": [ "{{base_url_dingo}}" ], "path": [ "domain", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Domain record id." } ] }, "description": "Fetch a single email domain, including its DKIM and verification details.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `domain` | object | id, domain, subdomain, status, dkim_names, verification. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Failed (Invalid Domain ID format)` | 400 | The `id` path segment is not a 24-character hexadecimal id. |\n| `Failed (Domain not found or unauthorized)` | 400 | No such domain, or not owned by this account. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"domain\": {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"domain\": \"example.com\",\n \"subdomain\": \"email\",\n \"status\": \"verified\",\n \"dkim_names\": [\n \"k1._domainkey\"\n ],\n \"verification\": \"verified\"\n }\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Create Domain", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/domain", "host": [ "{{base_url_dingo}}" ], "path": [ "domain" ] }, "description": "Register a new email domain. Email must be enabled and your plan's domain limit must not be exceeded.\n\n#### Request body parameters\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `domain` | string | Yes | Domain name (valid domain format). |\n| `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. |\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `error` | string | Empty on success. |\n| `message` | object | `{id, domain}`. |\n| `warning` | string | Present only when the subdomain was auto-corrected. |\n\n#### Errors\n| Error | HTTP | Cause |\n| --- | --- | --- |\n| `Email not enabled. Please contact us.` | 400 | Email is not enabled on this account. |\n| `Domain limit reached. Your plan allows {n} domain{s}. Please upgrade your plan or contact us.` | 400 | Plan domain limit reached. |\n| `Missing Domain` | 400 | `domain` not supplied. |\n| `Invalid Domain` | 400 | `domain` is not a valid domain. |\n| `Domain already registered. Please contact us.` | 400 | Domain already exists. |\n| `Invalid subdomain. Use only letters, numbers, and hyphens.` | 400 | `subdomain` contains invalid characters. |", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{\n \"domain\": \"example.com\",\n \"subdomain\": \"email\"\n}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"message\": {\n \"id\": \"683554c596937cc4b90f5cf7\",\n \"domain\": \"example.com\"\n }\n}" }, { "name": "400 Bad Request", "code": 400, "status": "Bad Request", "body": "{\n \"error\": \"Invalid Domain\"\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] } ] }, { "name": "Mailboxes", "description": "Hosted mailboxes on the shared mailbox domain — send-and-receive addresses that need no domain of your own. Your plan's mailbox quota caps how many active mailboxes the account may have. Mailboxes are never deleted via the API: `DELETE` returns `Unsupported method. Please see our API Docs` (HTTP 400). Disable a mailbox instead; mailboxes are removed only when the account closes.", "item": [ { "name": "List Mailboxes", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/mailboxes", "host": [ "{{base_url_dingo}}" ], "path": [ "mailboxes" ] }, "description": "List the hosted mailboxes on your account, active and inactive.\n\n#### Response fields\n| Field | Type | Description |\n| --- | --- | --- |\n| `mailboxes` | array | One object per mailbox. |\n| `mailboxes[].id` | string | Mailbox id (use with Enable / Disable Mailbox). |\n| `mailboxes[].address` | string | Full mailbox address. |\n| `mailboxes[].active` | boolean | `false` when the mailbox is disabled — inbound to it is dropped and it cannot send. |\n| `mailboxes[].created` | integer | Unix timestamp the mailbox was created, or `null`. |\n| `count` | integer | Number of mailboxes returned. |\n| `error` | string | Empty on success. |\n\n#### Errors\nNo endpoint-specific errors — authentication errors per the intro's 401 table.", "body": { "mode": "raw", "options": { "raw": { "language": "json" } }, "raw": "{}" } }, "response": [ { "name": "200 OK", "code": 200, "status": "OK", "body": "{\n \"error\": \"\",\n \"count\": 2,\n \"mailboxes\": [\n {\n \"id\": \"66a1f2c3d4e5f6a7b8c9d0e1\",\n \"address\": \"newsletter@mydingo.au\",\n \"active\": true,\n \"created\": 1753142400\n },\n {\n \"id\": \"66a1f2c3d4e5f6a7b8c9d0e2\",\n \"address\": \"old@mydingo.au\",\n \"active\": false,\n \"created\": 1750464000\n }\n ]\n}" }, { "name": "401 Unauthorized", "code": 401, "status": "Unauthorized", "body": "{\n \"error\": \"Failed (Invalid API ID or Key)\"\n}" } ] }, { "name": "Create Mailbox", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{base_url_dingo}}/mailboxes", "host": [ "{{base_url_dingo}}" ], "path": [ "mailboxes" ] }, "description": "Create a hosted mailbox. The new mailbox is active immediately and can send and receive at `