WhatsApp

Before you start

• Connect your WhatsApp Business Account (WABA) and phone number in the portal under WhatsApp. Until a number is connected, sends return 409 whatsapp_not_connected.
• Use an API key with the whatsapp:send permission (or a key without permission restrictions).
• Phone numbers are in E.164 format: a +, the country code and the number, without spaces, e.g. +60123456789.
• Meta bills conversations directly to the WABA owner. WhatsApp messages do not consume your email quota.

The 24-hour customer service window

WhatsApp only allows free-form messages (type: "text") while the customer service window is open, i.e. within 24 hours of the last message the customer sent you. Outside the window the request is rejected with 422 outside_service_window and you must send an approved template instead. Templates can be sent at any time.

Send a message

Template message

curl -X POST 'https://app.snappymails.com/v1/whatsapp/send' \
  -H "api-key: $SNAPPYMAILS_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+60123456789",
    "type": "template",
    "template": {
      "name": "order_update",
      "language": "en_US",
      "parameters": {
        "body": [
          "A-1077",
          "RM 42.50"
        ]
      }
    }
  }'

Text message (inside the 24-hour window)

curl -X POST 'https://app.snappymails.com/v1/whatsapp/send' \
  -H "api-key: $SNAPPYMAILS_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+60123456789",
    "type": "text",
    "text": {
      "body": "Your parcel is out for delivery: https://track.acme.com/A-1077",
      "preview_url": true
    }
  }'

201 Created

{
  "messageId": "7d9f1a52-3c4b-4e8a-9f61-2b0c5d7e8a13",
  "status": "QUEUED"
}

The message is queued and sent to Meta asynchronously. Poll its status with the message endpoint below.

Errors

Get a message

Returns the message with its current status and timestamps. Unknown ids (or ids of another brand) return 404 document_not_found.

curl 'https://app.snappymails.com/v1/whatsapp/messages/7d9f1a52-3c4b-4e8a-9f61-2b0c5d7e8a13' \
  -H "api-key: $SNAPPYMAILS_API_KEY" \
  -H 'Accept: application/json'

200 OK

{
  "id": "7d9f1a52-3c4b-4e8a-9f61-2b0c5d7e8a13",
  "direction": "OUTBOUND",
  "wa_message_id": "wamid.HBgLNjAxMjM0NTY3ODkVAgARGBI1...",
  "phone": "+60123456789",
  "contact_id": null,
  "contact_name": "Jane Doe",
  "campaign_id": null,
  "type": "template",
  "text": null,
  "template": {
    "name": "order_update",
    "language": "en_US",
    "parameters": { "body": ["A-1077", "RM 42.50"] }
  },
  "media": null,
  "status": "READ",
  "error": null,
  "source": "api",
  "created_at": "2026-10-16T09:00:00Z",
  "sent_at": "2026-10-16T09:00:01Z",
  "delivered_at": "2026-10-16T09:00:03Z",
  "read_at": "2026-10-16T09:02:47Z",
  "failed_at": null
}