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:
| Parameter | Default | Rules |
|---|---|---|
limit | 1000 | Records 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. |
offset | 0 | Number of records to skip before the page starts. |
The response has a pagination object:
"pagination": { "limit": 1000, "offset": 2000, "total": 19360 }
limitandoffset: the values that the API used. Use them, not the values you sent, because the API can changelimit.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 at1.per_page: records per page. The default is100and the maximum is1000.
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
- Get all lists and Get unsubscribers return all records in one response.
- Get SMS status accepts a maximum of 1000 SMS IDs in
ids. More IDs give a400error. Split large sets into groups of 1000.
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
403with 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:
| Scope | Limit | Error |
|---|---|---|
| One phone number | 3 codes in 15 minutes | Too many verification requests for this number, please wait 15 minutes |
| Your account | 5 codes in 1 minute | Rate limit exceeded, please wait before sending more verification requests |
| Your account | 50 codes in 1 hour | Hourly verification limit exceeded |
| Your account | 500 codes in 24 hours | Daily 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.