SimpleSMSDocs

Export messages, delivery results, events, opt-outs, webhook deliveries, usage, credit history or the audit log as CSV

GET /v1/exports/{kind}

Streams a CSV (UTF-8 with BOM). At most 50,000 rows per export (header X-Export-Row-Cap); narrow the date range if you hit it. Cells that would be spreadsheet formulas are prefixed with a single quote.

Send your API key as a bearer token: Authorization: Bearer ssms_sk_.... Test keys run this endpoint against the sandbox; see Authentication for key modes and scopes.

Path parameters

NameTypeRequiredDescription
kindmessages, deliveries, events, opt_outs, webhook_deliveries, usage, usage_monthly, audit_log, credit_historyYes

Query parameters

NameTypeRequiredDescription
fromstringNoISO date/time or epoch ms (messages, deliveries, events, webhook_deliveries) Example: 2026-01-01.
tostringNoInclusive; a bare date means the end of that day (UTC) Example: 2026-01-31.
statusqueued, sent, delivered, failed, receivedNomessages, deliveries
directionoutbound, inboundNomessages
numberstringNomessages, deliveries: digits matched against either side
to_numberstringNomessages, deliveries: exact recipient (E.164). to/from are the date range here.
from_numberstringNomessages, deliveries: exact sender (E.164)
customer_idstringNomessages, deliveries
batchstringNomessages, deliveries: batch id (bc_...)
qstringNomessages: body/failure text; events: id/payload text
typestringNoevents, webhook_deliveries Example: message.failed.
endpoint_idstringNowebhook_deliveries (default: all endpoints)
okbooleanNowebhook_deliveries
monthsintegerNousage: daily rows for the last N months Default 3. Maximum 12. Minimum 1.
actionstringNoaudit_log: one action, or a group prefix with a trailing dot (team.)
actorstringNoaudit_log: actor id or part of the actor email
target_typestringNoaudit_log
created_afterstringNoaudit_log: same as on GET /audit-logs (from is accepted too)
created_beforestringNoaudit_log: same as on GET /audit-logs (to is accepted too)

Responses

StatusMeaningBody
200CSV bodyCSV (text/csv)
400Unknown kind or invalid filterError
401Missing, malformed, or revoked API keyError
402Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or chargedError
429Rate limit or quota exceededError

Errors

StatusWhen
400Unknown kind or invalid filter
401Missing, malformed, or revoked API key
402Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429Rate limit or quota exceeded

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

json
{
  "error": {
    "code": "invalid_request",
    "message": "What went wrong, in plain words.",
    "param": "the_field",
    "request_id": "req_a1B2c3D4e5F6g7H8"
  }
}

Examples

curl

bash
curl -X GET "https://api.joinsimplesms.com/v1/exports/messages" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY"

Node.js

The Node.js SDK does not wrap this endpoint yet; call it with fetch.

javascript
const res = await fetch('https://api.joinsimplesms.com/v1/exports/messages', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SIMPLESMS_API_KEY}`,
  },
});

if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.text();

Python

The Python SDK does not wrap this endpoint yet; call it over HTTP.

python
import json, os, urllib.request

req = urllib.request.Request(
    "https://api.joinsimplesms.com/v1/exports/messages",
    method="GET",
    headers={
        "Authorization": f"Bearer {os.environ['SIMPLESMS_API_KEY']}",
    },
)
with urllib.request.urlopen(req) as res:
    data = res.read().decode()

Related