SMS

Sending messages

Send an SMS from a number you own. The API checks the Canadian destination and CASL consent before anything reaches the carrier.

Sending SMS

Send a message using a provisioned number. The API validates the Canadian destination number, and checks CASL consent before delivery (CRTC DNCL checking coming soon).

// "from" is one of your HonkIO numbers; "to" is a real number you hold consent for.
// Reuse the idempotency key on a retry: it returns the original message instead of sending and charging again.
const { data, error } = await honkio.messages.send({
  from: '+1416XXXXXXX',
  to: '+1613XXXXXXX',
  body: 'Hello from HonkIO! 🇨🇦',
}, { idempotencyKey: 'order-1042-shipped' })
if (error) throw new Error(`${error.name}: ${error.message}`)
console.log(data.id, data.status)

# "from" is one of your HonkIO numbers; "to" is a real number you hold consent for.
# Reuse the idempotency key on a retry: it returns the original message instead of sending and charging again.
curl -X POST https://api.honkio.ca/v1/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "from": "+1416XXXXXXX",
    "to":   "+1613XXXXXXX",
    "body": "Hello from HonkIO! 🇨🇦"
  }'

Contacts (POST /v1/contacts) take a phone_number, an email, or both. Groups, broadcasts and allow/deny lists use contacts that have a phone number; adding one without is refused with 422 CONTACT_HAS_NO_PHONE, and clearing the phone of a contact in a group or list with 409 CONTACT_IN_USE.