ACE SEND API

List the messages ​

GET/v1/messages

Messages of the account, newest first, 100 a page: pass next_cursor as cursor for the next page (null on the last one). Filters: status, channel, to (E.164), reference (exact), template (name; of the channel when given, else of either channel), from / until (moments of acceptance, until exclusive). Without events. A key sees only the messages of its mode: a test key the test ones (test true), a live key the live ones. Keys with the status permission.

API key permission: status · Limit: 20 requests a second per key

Query parameters ​

FieldTypeRequiredDescription
statusstringOne of: accepted, queued, submitted, sent, delivered, read, rejected, failed, expired, cancelled.
tostringThe number in E.164; the + may be left out. Pattern: ^\+?[1-9][0-9]{5,14}$.
referencestringYour reference, exactly. Up to 64 characters.
channelstringOne of: whatsapp, sms.
templatestringThe name of a template (of the channel when given, else of either channel). Up to 64 characters.
fromstring (date-time)ISO 8601 moments of acceptance; a value without an offset is read in UTC. until is exclusive.
untilstring (date-time)
cursorstringnext_cursor of the previous page. Up to 64 characters.

Request ​

bash
curl "https://api.ace-send.com/v1/messages?status=delivered&from=2026-11-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer ak_live_YOUR_API_KEY"
js
const response = await fetch('https://api.ace-send.com/v1/messages?status=delivered&from=2026-11-01T00%3A00%3A00Z', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.ACE_SEND_API_KEY}`,
  },
})
const result = await response.json()

if (!response.ok) {
  // application/problem+json: result.code is stable, result.title is for people
  throw new Error(`${result.code}: ${result.title}`)
}
console.log(result)
python
import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['ACE_SEND_API_KEY']}",
}
response = requests.get(
    "https://api.ace-send.com/v1/messages",
    headers=headers,
    params={
        "status": "delivered",
        "from": "2026-11-01T00:00:00Z",
    },
    timeout=10,
)
result = response.json()

if not response.ok:
    # application/problem+json: result["code"] is stable, result["title"] is for people
    raise RuntimeError(f"{result['code']}: {result['title']}")
print(result)
php
<?php

// composer require guzzlehttp/guzzle
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.ace-send.com/v1/']);

$response = $client->request('GET', 'messages', [
    'headers' => [
        'Authorization' => 'Bearer '.getenv('ACE_SEND_API_KEY'),
    ],
    'query' => [
        'status' => 'delivered',
        'from' => '2026-11-01T00:00:00Z',
    ],
    'http_errors' => false,
]);
$result = json_decode((string) $response->getBody(), true);

if ($response->getStatusCode() >= 400) {
    // application/problem+json: $result['code'] is stable, $result['title'] is for people
    throw new RuntimeException($result['code'].': '.$result['title']);
}
print_r($result);

Response ​

200 OK ​

FieldTypeDescription
dataMessage[]
next_cursorstring, nullable
json
{
  "data": [
    {
      "id": "msg_CgdWeHQN4sPaZnXfh7kP5",
      "status": "delivered",
      "to": "+5521998120937",
      "from": null,
      "country": "BR",
      "channel": "whatsapp",
      "template": {
        "name": "welcome_bonus",
        "version": 3
      },
      "language": "pt",
      "reference": "crm-42",
      "text": "Olá Ana! Seu bônus BONUS10 já está ativo.",
      "text_masked": false,
      "segments": 1,
      "encoding": null,
      "price": {
        "amount": "0.062500",
        "currency": "USD"
      },
      "error": null,
      "test": false,
      "campaign": null,
      "created_at": "2026-11-02T12:00:00+00:00",
      "updated_at": "2026-11-02T12:00:04+00:00",
      "events": null
    },
    {
      "id": "msg_CgdWeHQNnp4VN7KkfNqju",
      "status": "delivered",
      "to": "+5511912345678",
      "from": "ACESEND",
      "country": "BR",
      "channel": "sms",
      "template": null,
      "language": null,
      "reference": "otp-7781",
      "text": "Your ACE SEND code is 482913. It expires in 10 minutes.",
      "text_masked": false,
      "segments": 1,
      "encoding": "gsm7",
      "price": {
        "amount": "0.018000",
        "currency": "USD"
      },
      "error": null,
      "test": false,
      "campaign": null,
      "created_at": "2026-11-02T12:00:00+00:00",
      "updated_at": "2026-11-02T11:58:12+00:00",
      "events": null
    }
  ],
  "next_cursor": "msg_CgdWeHQNnp4VN7KkfNqju"
}

Objects ​

Message object ​

FieldTypeDescription
idstringThe message, msg_….
statusstringOne of: accepted, queued, submitted, sent, delivered, read, rejected, failed, expired, cancelled.
tostringThe number in E.164.
fromstring, nullableThe sender name of an SMS; null for WhatsApp (its number is not shown) and for a test SMS.
countrystringISO 3166-1 alpha-2 of the number.
channelstringOne of: whatsapp, sms.
templateobject, nullableThe template and the number of the version the message was sent with; null for an own SMS text.
template.namestring
template.versioninteger
languagestring, nullableThe language of the template; null for an own SMS text.
referencestring, nullableYour own id of the message, as you sent it.
textstring, nullableThe text as sent; null once it is past its retention period (90 days, text_masked).
text_maskedbooleanWhether text was erased after the retention period (90 days).
segmentsintegerThe parts the SMS is sent and priced in (its price is the price of a segment times them); 1 for WhatsApp.
encodingstring, nullableThe encoding of the SMS: gsm7 (160 characters, 153 a segment of a longer text) or ucs2 (70, 67); null for WhatsApp. One of: gsm7, ucs2.
priceobject, nullableThe price fixed at acceptance, in the currency of the account; for an SMS, the price of a segment times segments. Null for a test message.
price.amountstring
price.currencystring
errorobject, nullableWhy the message did not reach the recipient: a stable code and a text in the language of Accept-Language. Null while it is on its way or when delivered.
error.codestring
error.textstring
testbooleanSent with a test key: through the sandbox, free.
campaignobject, nullableThe console campaign that sent the message; null for a message of the API.
campaign.idstring
campaign.namestring
created_atstringWhen the message was accepted.
updated_atstringWhen the message last changed.
eventsobject[], nullableThe history of statuses, oldest first. Only in GET /messages/{id}; null elsewhere.
events[].statusstring
events[].atstring
events[].errorobject, nullable
events[].error.codestring
events[].error.textstring

Errors ​

Errors are application/problem+json with a stable code (all codes). Besides the errors of every request (an invalid key, a missing permission, too many requests), this endpoint answers:

StatusCodeMeaning
422validation_failedSome fields are wrong: errors lists each field with its code and a message.
json
{
  "type": "about:blank",
  "status": 422,
  "code": "validation_failed",
  "title": "Check the form fields",
  "errors": [
    {
      "field": "variables.promo_code",
      "code": "required",
      "message": "Fill in this field"
    }
  ]
}

ACE SEND API v1

© ACE SEND