POST /api/campaigns/upload For audiences larger than 10,000 users, upload a CSV file containing user IDs and optional per-user template variable values. The CSV is parsed server-side, recipients are created, and delivery is triggered through the campaign system.

​
How does CSV batch delivery work?

  1. Create a campaign linked to an approved template
  2. Upload a CSV file with user IDs and variable columns to the campaign
  3. Send the campaign
CSV batch delivery uses the campaign system (unlike the one-call send API). This gives you campaign lifecycle tracking, scheduling, and recipient status monitoring.

​
How do I create the CSV file?

The CSV must include:
  • A user_id column (required) containing the target user IDs
  • Additional columns for template variable values (optional) — column names must match the variable keys in the template’s variableSchema
user_id,name,appointment_number
user-1,Bob,32893
user-2,Alice,44521
user-3,Charlie,55102
The maximum number of rows in a single CSV file is 100,000. The user_id column is required — uploads without it will fail.

​
CSV rules

RuleDetail
First rowMust be column headers
user_id columnRequired — contains target user IDs
Variable columnsOptional — names must match template variableSchema keys
Column namesLetters, numbers, underscores, hyphens only
Max rows100,000
EncodingUTF-8
DelimiterComma

​
Step 1: Create a campaign

curl -X POST https://{appId}.api-{region}.cometchat.io/v3/business-messaging/api/campaigns \
  -H "appid: YOUR_APP_ID" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday Promotion",
    "templateId": "TEMPLATE_ID",
    "deliveryMode": "batch",
    "tag": "marketing"
  }'
Save the campaign id from the response.

​
Step 2: Upload the CSV

POST /api/campaigns/upload Upload the CSV as a multipart form with the campaign ID.

​
Headers

​
appid
string
required
Your CometChat App ID.
​
apikey
string
required
Your CometChat API Key.

​
Form fields

​
file
file
required
The CSV file containing user_id and optional variable columns.
​
campaignId
string
required
The campaign ID to add recipients to.

​
Example request

curl -X POST https://{appId}.api-{region}.cometchat.io/v3/business-messaging/api/campaigns/upload \
  -H "appid: YOUR_APP_ID" \
  -H "apikey: YOUR_API_KEY" \
  -F "file=@recipients.csv" \
  -F "campaignId=CAMPAIGN_ID"

​
Example response

{
  "recipientsAdded": 50000
}
​
recipientsAdded
integer
The number of recipients successfully parsed and added from the CSV.

​
Step 3: Send the campaign

curl -X POST https://{appId}.api-{region}.cometchat.io/v3/business-messaging/api/campaigns/CAMPAIGN_ID/send \
  -H "appid: YOUR_APP_ID" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

​
How do CSV variable columns work?

When your template has a variableSchema, the CSV columns beyond user_id are mapped to variable keys: Template variableSchema: 
[
  { "key": "name", "type": "string", "name": "Customer Name", "required": true },
  { "key": "discount_code", "type": "string", "name": "Discount Code", "required": true }
]
CSV file: 
user_id,name,discount_code
user-1,Bob,SAVE20
user-2,Alice,SAVE30
user-3,Charlie,VIP50
Each user receives a personalized notification with their specific name and discount_code values substituted into the template content.
String variable values are taken directly from CSV cells. For image and action variable types, provide the value as a JSON string in the CSV cell.

​
Comparing inline targets vs CSV upload

FeatureInline targetsCSV upload
Max users10,000100,000
API calls1 (one-call send)3 (create campaign, upload CSV, send)
VariablesIn request bodyIn CSV columns
SchedulingNot supportedSupported via scheduledAt
Lifecycle trackingNo campaign entityFull campaign lifecycle
Status monitoringAnalytics onlyCampaign status + recipient status

​
Error codes

CodeHTTPDescription
ERR_BAD_REQUEST400Missing user_id column or invalid CSV format
ERR_NOT_FOUND404Campaign not found
ERR_OPERATION_FAILED500CSV parsing or recipient creation failed