Skip to Content
Developer docsBeta

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:

customers.csv
phone,name,code
+201001234567,Mona,EID20
+201112223334,Karim,EID15
import { 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" }
  ]
}
  • skipped lists the numbers left out of the campaign, by their position in recipients: invalid_number (not a valid mobile number) or duplicate (the same number, or another number of the same customer, came earlier). If none is valid, the request fails with 422 no_valid_recipients.
  • total counts the campaign's rows, including customers who opted out: they're in the campaign as skipped (opted_out) from the start and are never sent.
  • pacingAdjusted: true means 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:

skipReasonWhy
opted_outThe customer opted out of your messages.
frequency_capThey got a campaign message recently (marketing only).
contact_deletedThe customer was deleted from your contacts before the send.
offer_endedA 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.

On this page