API guide

Getting started

The SMSEdge API lets your software send SMS, manage contact lists, verify phone numbers, send one-time codes and read delivery reports. This guide takes you from no API key to your first sent message in about 10 minutes.

Base URL

Send all requests to this base URL over HTTPS:

https://api.smsedge.com

Each endpoint path starts with the API version, for example /v1/sms/send-single/. Every response is JSON.

1. Get your API key

  1. Log in to app.smsedge.com.
  2. Open API settings.
  3. In API Tokens, click Create Token.
  4. Type a name for the token, for example Production server. You can also set an expiry date.
  5. Copy the token and keep it in a safe place.

Your API key gives full access to your account and balance. Keep it on your server. Do not put it in a mobile app, in browser code or in a public repository. See Authentication.

2. Make your first call

Send your key in the X-API-KEY header. This call returns your account details and balance. It costs nothing.

curl https://api.smsedge.com/v1/user/details/ \
  -H "X-API-KEY: YOUR_API_KEY"
const res = await fetch('https://api.smsedge.com/v1/user/details/', {
  headers: { 'X-API-KEY': process.env.SMSEDGE_API_KEY },
})
const [body] = await res.json()
console.log(body.data.balance)

A correct key gives a response like this:

[
  {
    "success": true,
    "data": {
      "id": 12345,
      "username": "acme",
      "email": "dev@example.com",
      "balance": 102.479247,
      "registered": "2024-06-29 10:29:29",
      "optout_link": "http://example.click/aB",
      "login_url": "https://app.smsedge.com/v2/login?authkey=..."
    },
    "errors": [],
    "response": { "code": 200, "description": "OK", "date": "2026-11-16 13:58:52" },
    "api": { "version": "v1", "module": "user", "function": "details" },
    "user": { "id": 12345 }
  }
]

The response body is a JSON array with one object in it. Read the first item, for example body[0].data. See Responses and errors.

If you get 401 and Valid API key not specified, the key is wrong, expired or revoked. Copy it again from API settings. Reference: Get account details.

3. Send an SMS

Send to, from and text to /v1/sms/send-single/. Write the number in international format, digits only.

curl -X POST https://api.smsedge.com/v1/sms/send-single/ \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d "to=447700900123" \
  -d "from=Acme" \
  -d "text=Your order 1042 has shipped." \
  -d "reference=order-1042"
const res = await fetch('https://api.smsedge.com/v1/sms/send-single/', {
  method: 'POST',
  headers: { 'X-API-KEY': process.env.SMSEDGE_API_KEY },
  body: new URLSearchParams({
    to: '447700900123',
    from: 'Acme',
    text: 'Your order 1042 has shipped.',
    reference: 'order-1042',
  }),
})
const [body] = await res.json()
if (!body.success) throw new Error(body.errors.join(', '))
console.log('SMS id', body.data.id)

The response has the SMS in data. Keep data.id. You use it to read the status, and webhooks send it to you. The reference is your own value. It comes back in the status and in webhooks.

All parameters, such as the sender, the route and link shortening, are in Send a single SMS. To send to a full list, use Send to a list.

4. Check the delivery status

Send the SMS id in ids:

curl "https://api.smsedge.com/v1/sms/get/?ids=123456789" \
  -H "X-API-KEY: YOUR_API_KEY"

Two fields tell you the state of the message:

  • status: what SMSEdge did with the message. waiting, sent or failed.
  • dlr_status: the delivery report from the network, for example Delivered, Expired or Undeliverable. It is unknown until the network answers.

Reference: Get SMS status.

Do not poll for each message. Set a webhook URL, and SMSEdge sends you each delivery report when it arrives. See Webhooks.

Next steps