Sending to many numbers
One request, up to 10,000 recipients, each with its own variables.
Sending to many numbers is the same request with more recipients: up to 10,000 per campaign. Each recipient carries its own variables, so every customer gets their own name, code or link.
{
"name": "Eid offer",
"template": { "id": "tpl_8Kq2mZ" },
"from": "num_3Fh7Ws",
"scheduledAt": "2026-12-01T09:00:00+02:00",
"recipients": [
{ "phone": "+201001234567", "externalId": "cus_1", "variables": { "body": ["Mona"] } },
{ "phone": "+201112223334", "externalId": "cus_2", "variables": { "body": ["Karim"] } }
]
}From a CSV to JSON
Most lists start as a spreadsheet. Export it as CSV with a header row and turn each row into a recipient:
phone,name,code
+201001234567,Mona,EID20
+201112223334,Karim,EID15import { readFileSync } from 'node:fs';
// For real files with quotes or commas inside cells, use a CSV parser such as csv-parse.
const [header, ...rows] = readFileSync('customers.csv', 'utf8').trim().split('\n');
const cols = header.split(',');
const recipients = rows.map((line) => {
const row = Object.fromEntries(line.split(',').map((v, i) => [cols[i], v.trim()]));
return { phone: row.phone, name: row.name, variables: { body: [row.name, row.code] } };
});Phone numbers in spreadsheets
Spreadsheets often drop the leading + or 0. Send E.164 (+201001234567); a local Egyptian
number with its 0 (01001234567) also works and is read as +20. Any other number needs its
country code.
More than 10,000 numbers
Split the list into chunks of up to 10,000 and send one campaign per chunk, each with its own
Idempotency-Key (eid-offer-part-1, eid-offer-part-2…). Mawgood paces each number's sends, so
starting the chunks together doesn't make delivery faster.
Idempotency
Idempotency-Key is required. A large request can time out on your side after Mawgood accepted
it; retrying with the same key returns that campaign (idempotent-replay: true) instead of sending
the list a second time. See the Idempotency-Key header.
The response
{
"id": "cmp_9Xa4Lr",
"status": "preparing",
"total": 900,
"pacing": { "mode": "steady", "overHours": 6 },
"pacingAdjusted": true,
"estimatedCredits": 897,
"skipped": [
{ "index": 12, "phone": "0223456789", "reason": "invalid_number" },
{ "index": 40, "phone": "+201001234567", "reason": "duplicate" }
]
}skippedlists the numbers left out of the campaign, by their position inrecipients:invalid_number(not a valid mobile number) orduplicate(the same number, or another number of the same customer, came earlier). If none is valid, the request fails with422 no_valid_recipients.totalcounts the campaign's rows, including customers who opted out: they're in the campaign asskipped(opted_out) from the start and are never sent.pacingAdjusted: truemeans Mawgood picked or raised the pacing to fit your all-at-once limit. See Rate limits & pacing.
Review mode
In some workspaces, campaigns wait for the Mawgood team's approval and start as in_review. Once
approved they move on to scheduled or preparing on their own, and you get campaign.started
when sending begins. If the team rejects one, you get campaign.rejected with a reviewNote, and
nothing is sent.
Who gets skipped later
Once the campaign runs, a recipient can still be skipped, with a skipReason:
skipReason | Why |
|---|---|
opted_out | The customer opted out of your messages. |
frequency_cap | They got a campaign message recently (marketing only). |
contact_deleted | The customer was deleted from your contacts before the send. |
offer_ended | A dashboard campaign's limited-time offer ended before the send. |
WhatsApp's own limit on marketing messages per person isn't a skip: Meta refuses the message, so it
is failed with Meta's code in error.code (for example 131049).
See Marketing vs utility for which rules apply to which templates.