SMS Campaign
/api/v2/sms/campaign/send Base URL https://api.easify.liveBearer token and Accept header required Authentication →
This endpoint is used to send SMS campaigns using predefined SMS templates.
Users can fetch SMS templates using the SMS Templates API and then use those templates to send SMS campaigns.
There is a rate limit of 15 requests per minute per API token. This count is shared by all API endpoints, including GET requests, except those with their own separate limit (/api/v2/sms/send, /api/v3/sms/send, etc.), so this endpoint is refused once your token has made 15 requests to the shared endpoints within a minute. If you exceed this limit, you will receive a 429 Too Many Requests status, along with a message indicating when you can try again.
Each campaign supports up to 10,000 recipients, with recipient data uploaded as a CSV file following the sample format provided.
Download Recipients Sample File
The authenticated user must have access to the SMS feature. Requests made without the proper feature permissions will receive a 490 status code response, indicating that a plan upgrade is required.Request Body
| campaign_name string | Name for the Campaign | Required |
| from_numbers array |
From number(s) to send Campaign *Ensure that you are using a phone number associated with the api token, please use the Phone Numbers API to retrieve the associated phone numbers. *Include the country code (e.g., +17473194***). A missing + is added, but a country code is not, so a 10-digit number is rejected. *Every number must be active, approved, assigned to the API token's user and allowed for campaigns. If any number fails this check, the whole request is rejected. | Required |
| template_ids array |
Templates IDs to send campaign *Use the SMS Templates API to retrieve the available templates and obtain their IDs. |
Required |
| recipients_file file | Recipients' data (The file must be in CSV format) | Required |
| schedule_time string |
Campaign Schedule time, in the schedule_timezone Must be in the format YYYY-MM-DD HH:MM:SS (e.g., 2025-08-28 06:01:58). Any other format returns a 400 error. |
Optional |
| schedule_timezone string | Timezone for the scheduled campaign, using IANA format (e.g., America/New_York). An unknown timezone returns a 400 error. | Required with schedule_time |
Example Request and Response
Request:
{
"campaign_name": "New Campaign",
"from_numbers": ["+17473194***", "+19598000***"],
"template_ids": [1457, 1448],
"recipients_file": "recipients.csv"
}
The recipients_file must be uploaded as a CSV file in multipart/form-data, not JSON.
Success Response:
{
"status": true,
"message": "SMS Campaign Processed Successfully",
"data": {
"campaign_id": 31529,
"recipients_in_file": 10000,
"valid_recipients": 10000,
"invalid_recipients": 0
}
}
Success Response Data:
| Key | Description |
|---|---|
| campaign_id | The unique identifier of the SMS campaign |
| recipients_in_file | Total number of recipients provided in the uploaded file. |
| valid_recipients | Number of recipients with valid phone numbers that were successfully processed |
| invalid_recipients | Number of recipients skipped due to invalid phone numbers or incorrect phone number formats (e.g., not matching the required format in the sample file) |
Responses
| Case | Status Code | Response |
|---|---|---|
| If the user provides an invalid Easify API token or does not pass the Easify API token in the header. | 401 |
{
"status":false,
"message":"Unauthenticated",
"errors":[]
}
|
| If the user exceeds the allowed rate limit for requests | 429 |
{
"status":false,
"message":"Too many requests. Try again in 59 seconds",
"errors":[]
}
|
| If the user's subscription has ended | 402 |
{
"status":false,
"message":"You need to recharge your account to proceed",
"errors":[]
}
|
| If the user provides an invalid format for the recipients_file | 422 |
{
"message": "The file must be a valid CSV file.",
"errors": {
"recipients_file": [
"The file must be a valid CSV file."
]
}
}
|
| If the user uploads a recipients_file larger than 5 MB | 422 |
{
"message": "The file size cannot exceed 5 MB.",
"errors": {
"recipients_file": ["The file size cannot exceed 5 MB." ]}
}
|
| If the recipients_file CSV contains more than 10,000 rows | 422 |
{
"message": "The CSV file cannot contain more than 10,000 rows.",
"errors": {
"recipients_file": ["The CSV file cannot contain more than 10,000 rows."]}
}
|
| If the user has not completed 10DLC registration | 400 |
{
"status": false,
"message": "You must complete the 10DLC registration process before creating a campaign.",
"errors": []
}
|
| If no valid phone numbers are found in the from numbers | 400 |
{
"status": false,
"message": "No valid phone number(s) found in the selected numbers.",
"errors": []
}
|
| If the campaign cannot proceed due to insufficient credits | 400 |
{
"status": false,
"message": "Campaign cannot proceed due to low credits. Please add more credits to continue.",
"errors": []
}
|
| If the user exceeds their daily SMS segment limit | 400 |
{
"status": false,
"message": "Your daily SMS segment limit of xxx has been exceeded! Please contact the admin to increase the limit.",
"errors": []
}
|
| If the user provided template IDs are invalid | 400 |
{
"status": false,
"message": "Invalid templates.",
"errors": []
}
|
| If the user provided lengthy campaign name | 422 |
{
"message": "The campaign name field must not be greater than 44 characters.",
"errors": {
"campaign_name": [
"The campaign name field must not be greater than 44 characters."
]}
}
|
| If the user provided very short campaign name | 422 |
{
"message": "The campaign name field must be at least 2 characters.",
"errors": {
"campaign_name": [
"The campaign name field must be at least 2 characters."
]
}
}
|
| If the user uploads a recipients file containing some invalid phone numbers | 400 |
{
"status": true,
"message": "SMS Campaign Processed Successfully, with certain recipients skipped due to invalid phone numbers or formats.",
"data": {
"campaign_id": 3475,
"recipients_in_file": 10000,
"valid_recipients": 1,
"invalid_recipients": 9999
}
}
|
| When the user account is inactive | 403 |
{
"status": false,
"message": "Your account is currently inactive.",
"errors": []
}
|
| If the request comes from an IP address or domain that is not on the account's API whitelist | 400 |
{
"status": false,
"message": "Access denied! Your IP or domain is not whitelisted.[ HostName : ] - [ Ip Address : << YOUR_SERVER_IP >>]",
"errors": []
}
|
Code Examples
php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.easify.live/api/v2/sms/campaign/send',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
// Sent as multipart/form-data, not JSON. Repeated fields are indexed so both
// from numbers and both template ids arrive as arrays.
CURLOPT_POSTFIELDS => [
'campaign_name' => 'New Campaign',
'from_numbers[0]' => '+17473194***',
'from_numbers[1]' => '+19598000***',
'template_ids[0]' => '1457',
'template_ids[1]' => '1448',
'recipients_file' => new CURLFile('recipients.csv', 'text/csv', 'recipients.csv'),
],
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <> ',
'Accept: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;