Skip to Content
Developer docsBeta

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

FieldRequiredNotes
templateyes{ "id": "tpl_…" }, or { "name": "…", "language": "ar" }. Must be approved.
recipients[].phoneyesE.164 (+201001234567). A local Egyptian number (01001234567) is read as +20.
recipients[].variableswhen the template has themSee Template variables.
recipients[].namenoUp to 80 characters. Saved on the CRM contact when Mawgood creates one.
recipients[].externalIdnoYour own id, up to 255 characters. Comes back in recipients and webhooks.
fromnoA number id from GET /numbers. Needed only when more than one number can send the template.
scheduledAtnoSend later (ISO 8601 with an offset, e.g. 2026-12-01T09:00:00+02:00). In the past: now.
pacingno{ "mode": "all_at_once" } or { "mode": "steady", "overHours": 6 }. See pacing.
namenoUp 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 keyAnswer
Same body202 with the first answer and the header idempotent-replay: true. Nothing is sent again.
Another body409 idempotency_conflict.
While the first is still running409 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 (with name if 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.replied webhook.

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.

On this page