Sending to one number
Order updates, reminders and receipts — one template to one customer.
A single message is a campaign with one recipient. Use it for transactional messages your system triggers: an order shipped, an appointment tomorrow, a payment received.
curl https://api.mawgood.ai/v1/campaigns \
-H "Authorization: Bearer $MAWGOOD_API_KEY" \
-H "Idempotency-Key: order-1042-shipped" \
-H "Content-Type: application/json" \
-d '{
"template": { "name": "order_shipped", "language": "ar" },
"recipients": [
{
"phone": "+201001234567",
"name": "Mona",
"externalId": "order-1042",
"variables": { "body": ["Mona", "#1042"], "buttons": { "0": "1042" } }
}
]
}'The fields
| Field | Required | Notes |
|---|---|---|
template | yes | { "id": "tpl_…" }, or { "name": "…", "language": "ar" }. Must be approved. |
recipients[].phone | yes | E.164 (+201001234567). A local Egyptian number (01001234567) is read as +20. |
recipients[].variables | when the template has them | See Template variables. |
recipients[].name | no | Up to 80 characters. Saved on the CRM contact when Mawgood creates one. |
recipients[].externalId | no | Your own id, up to 255 characters. Comes back in recipients and webhooks. |
from | no | A number id from GET /numbers. Needed only when more than one number can send the template. |
scheduledAt | no | Send later (ISO 8601 with an offset, e.g. 2026-12-01T09:00:00+02:00). In the past: now. |
pacing | no | { "mode": "all_at_once" } or { "mode": "steady", "overHours": 6 }. See pacing. |
name | no | Up to 80 characters, shown in the dashboard. Defaults to the template's name. |
The Idempotency-Key header
Networks fail. If your request times out, you can't know whether Mawgood received it. So
Idempotency-Key is required (up to 255 characters; without it the request fails with
422 validation_failed). Build it from something unique in your system (order-1042-shipped) and
retry freely for 24 hours:
| Retry with the same key | Answer |
|---|---|
| Same body | 202 with the first answer and the header idempotent-replay: true. Nothing is sent again. |
| Another body | 409 idempotency_conflict. |
| While the first is still running | 409 idempotency_in_progress: wait a moment and retry. |
A request that was refused (any 4xx) frees its key, so you can fix it and send it again with the
same one.
What happens to the customer
- A number Mawgood hasn't seen becomes a CRM contact tagged
api(withnameif you sent one). - The message appears in the customer's conversation in the Mawgood inbox.
- When the customer replies, your Mawgood answers, with your instructions and knowledge, and your
team can step in from the inbox. You also get a
message.repliedwebhook.
Following it
The response's id is the campaign. Either listen for webhooks (recommended) or read
GET /campaigns/{id}/recipients to see the message's status, timestamps and, if it failed, why.