API guide

Authentication

Every API request must include your API key. The key identifies your account, so all lists, messages and charges belong to that account.

Send the key in the X-API-KEY header

Put the key in the X-API-KEY HTTP header of each request:

curl https://api.smsedge.com/v1/lists/getall/ \
  -H "X-API-KEY: YOUR_API_KEY"
import os
import requests

res = requests.get(
    "https://api.smsedge.com/v1/lists/getall/",
    headers={"X-API-KEY": os.environ["SMSEDGE_API_KEY"]},
    timeout=30,
)
body = res.json()[0]
print(body["success"], body["data"])
<?php
$ch = curl_init('https://api.smsedge.com/v1/lists/getall/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-KEY: ' . getenv('SMSEDGE_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true)[0];
curl_close($ch);

Get and manage keys

  1. Open API settings in the SMSEdge app.
  2. In API Tokens, click Create Token. Give each server or integration its own token.
  3. Optional: set an expiry date. After that date the token stops working.
  4. To stop a token at once, revoke it in the same page.

Use one token for each system. Then you can revoke one token without stopping your other integrations.

Failed authentication

If the key is missing, wrong, expired or revoked, or the account is blocked, the API returns HTTP 401:

[
  {
    "success": false,
    "data": [],
    "errors": ["Valid API key not specified"],
    "response": { "code": 401, "description": "Authentication Failure", "date": "2026-11-16 13:59:03" },
    "api": { "version": "v1", "module": "lists", "function": "getall" }
  }
]

A 401 response has no user object. Do not retry a 401 with the same key. Check the key in API settings first.

Keep your key secret

  • Keep the key on your server, for example in an environment variable or a secrets manager.
  • Do not put the key in a mobile app, in JavaScript that runs in the browser or in a public repository. Anyone who has the key can send messages and spend your balance.
  • Do not write the key in logs, error reports or support tickets.
  • If a key leaks, revoke it in API settings at once and create a new one.

Legacy: the api_key parameter

Older integrations send the key as an api_key query or form parameter. The API still accepts it when there is no X-API-KEY header, so old code continues to work.

Do not use api_key in new code. A key in the URL can be stored in server logs, proxy logs and browser history. Use the X-API-KEY header. All examples in these docs use the header.