Send a message

Transactional SMS request body, response, and fields

Recipients must be E.164. Content supports up to 1,600 characters and is billed in GSM-7 or Unicode segments. from must be an approved sender.

requestcURL · POST /messages

curl -X POST https://ecowave-api.builds.et/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ew_live_PUBLIC_ID_SECRET" \
  -H "Idempotency-Key: otp-user-42-20260808" \
  -d '{
    "to": "+251911234567",
    "text": "Your verification code is 482913.",
    "webhook": {
      "url": "https://example.com/webhooks/ecowave",
      "secret": "replace-with-16-plus-chars"
    }
  }'

response202 Accepted · JSON

{
  "id": "7f8d9e1a-4b2c-4d5e-9f01-234567890abc",
  "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "from": "EcoWave",
  "to": "+251911234567",
  "text": "Your verification code is 482913.",
  "status": "queued",
  "segments": 1,
  "providerMessageId": null,
  "errorCode": null,
  "errorMessage": null,
  "metadata": {},
  "environment": "live",
  "createdAt": "2026-08-08T09:12:04.000Z",
  "acceptedAt": null,
  "sentAt": null,
  "deliveredAt": null,
  "failedAt": null
}

Body fields

FieldTypeDescription

tostring · required

E.164 number, 8–16 characters.

textstring · required

Non-empty SMS body, max 1,600 characters.

fromstring · optional

Approved sender ID, max 20 characters.

metadataobject · optional

Your correlation data, returned with the message.

webhookobject · optional

url and optional secret for status callbacks.

A 202 means the message was persisted and queued — not delivered to the handset. Save id and wait for a terminal status.