API guide

Pagination and limits

Endpoints that can return many records give them one page at a time. This page tells you how to get all pages, and which limits apply to your account.

Pagination with limit and offset

These endpoints use limit and offset:

ParameterDefaultRules
limit1000Records per page, from 1 to 1000. A value less than 1 or more than 1000 becomes 1000. The API does not return an error for it.
offset0Number of records to skip before the page starts.

The response has a pagination object:

"pagination": { "limit": 1000, "offset": 2000, "total": 19360 }
  • limit and offset: the values that the API used. Use them, not the values you sent, because the API can change limit.
  • total: the number of records that match your filters, on all pages.

To get all records, add limit to offset after each page. Stop when offset is equal to or more than total.

import os
import requests

URL = "https://api.smsedge.com/v1/numbers/get/"
HEADERS = {"X-API-KEY": os.environ["SMSEDGE_API_KEY"]}

numbers, offset, limit = [], 0, 1000
while True:
    body = requests.get(
        URL,
        headers=HEADERS,
        params={"list_id": 347617, "limit": limit, "offset": offset},
        timeout=60,
    ).json()[0]
    if not body["success"]:
        break  # 404 "No numbers found" after the last page
    numbers.extend(body["data"])
    offset += body["pagination"]["limit"]
    if offset >= body["pagination"]["total"]:
        break

print(len(numbers), "numbers")

A page after the last record returns 404 with success: false, not an empty 200. Use total to stop, or treat this 404 as the end.

Pagination with page and per_page

The campaign list endpoint (/v1/campaigns/getall/) uses page numbers:

  • page: the page number. It starts at 1.
  • per_page: records per page. The default is 100 and the maximum is 1000.

Its pagination object has page, per_page and all, which is the number of pages. A page after the last page returns 200 with an empty data array.

Endpoints with no pagination

Request rate

The v1 API has no fixed limit on the number of requests for each second. Be reasonable: send requests at a steady rate, and do not send many requests in parallel to read the same data. To send to many numbers, use Send to a list, not thousands of single requests at the same time.

Daily sending limit

An account can have a daily sending limit. This limit is an amount of money: the total cost of the messages that you can send in one day. SMSEdge sets it on your account. You cannot change it through the API.

  • The limit applies to Send a single SMS and Send to a list.
  • The day starts at 00:00 server time.
  • When you reach the limit, send requests return 403 with this error until the next day:
"errors": ["You have reached your sending limit for the day, To keep sending please contact us."]

To get a higher limit, contact your account manager or SMSEdge support.

A new account can also get 403 with Account waiting activation. Sending through the API starts after SMSEdge activates your account.

Balance

Messages, HLR lookups and verification codes are paid from your balance. When the balance is too low, requests fail. Check your balance with Get account details.

Phone verification limits

Send a verification code has its own limits to prevent abuse:

ScopeLimitError
One phone number3 codes in 15 minutesToo many verification requests for this number, please wait 15 minutes
Your account5 codes in 1 minuteRate limit exceeded, please wait before sending more verification requests
Your account50 codes in 1 hourHourly verification limit exceeded
Your account500 codes in 24 hoursDaily verification limit exceeded

These errors use HTTP 400. If you need higher account limits, contact SMSEdge support. The limit for one phone number always applies.