Recipient profiles

The profile

A profile is keyed by your own user ID, the same user_id your push devices are registered under. It holds contact details only: phone_number (E.164, a Canadian number), email and language (en or fr, default en). It holds no channel preferences: who is reached on what is decided by the order you send in.

A profile answers with object, user_id, phone_number, email, language, livemode, devices (the person’s active push devices: phones and browsers) and its timestamps.

Writing a phone number or an email address here is not consent. Notify checks consent, opt-outs, suppressions and sending limits exactly as the SMS and email APIs do.

const { data: recipient, error } = await honkio.recipients.upsert('user_1042', {
  phoneNumber: '+1416XXXXXXX',
  email: 'pat@example.com',
  language: 'en',
})
if (error) throw new Error(error.message)
console.log(recipient.user_id, recipient.devices)

from honkio import Honkio

client = Honkio()  # reads HONKIO_API_KEY

recipient = client.recipients.upsert(
    "user_1042",
    phone_number="+1416XXXXXXX",
    email="pat@example.com",
    language="en",
)
print(recipient["user_id"], recipient["devices"])

<?php

use Honkio\Honkio;

$honkio = new Honkio(); // reads HONKIO_API_KEY

$recipient = $honkio->recipients->upsert('user_1042', [
    'phone_number' => '+1416XXXXXXX',
    'email' => 'pat@example.com',
    'language' => 'en',
]);
echo $recipient['user_id'], ' ', $recipient['devices'], PHP_EOL;

curl -X PUT https://api.honkio.ca/v1/recipients/user_1042 \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1416XXXXXXX",
    "email": "pat@example.com",
    "language": "en"
  }'

Keeping profiles

PUT /v1/recipients/:user_id creates the profile or replaces every field of it: a field left out is cleared and the language goes back to en. PATCH changes only the fields you send, and null clears one. GET reads one or lists them with a cursor, and DELETE removes one.

Deleting a profile also unregisters that user's push devices in the same mode, so the key needs push_devices delete permission as well (the same permission DELETE /v1/push/devices needs). Without it the call is refused with 403 FORBIDDEN (reason push_devices_permission_required) while the user has active devices, and nothing changes. It also clears the text of that user's notifications in the mode, and a notification still pending sends nothing more.

The key needs recipients permission: r to read, w to create, m to replace or change and d to delete. A key with w but not m can create a profile but not replace one that exists.

Deleting a profile erases only that: the profile, the devices and the notifications' text. The messages, emails and pushes those notifications sent keep their text and the number or address they went to until retention clears them, and a profile's user_id stays on past notification and push records. To erase a phone number everywhere, use POST /v1/compliance/erasure. Do not use an email address or a phone number as the user_id if you rely on deleting a profile for erasure.

An account holds up to 1,000,000 profiles in live mode and 1,000 in test mode. Creating one past that is refused with 409 RECIPIENT_LIMIT_REACHED; replacing or changing an existing profile always works.

Live and test

Profiles are kept per key mode, like consents: a test key reads and writes test profiles, a live key live ones, and a profile of the other mode answers 404 RECIPIENT_NOT_FOUND. The dashboard's Recipients page follows its Live and Test switch the same way.