SMS Campaign

POST/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

Send an SMS campaign
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;