SDKs

Install and quickstart

Install the package, then create a client with an API key.

npm install @honkio/node

@honkio/node runs on Node 18 or newer, ships as ESM and CommonJS, and has no runtime dependencies. @honkio/node on npm

Create a key in the dashboard under API Keys → Create key; the full key is shown once, right after you create it. Start with a test key (mk_test_...): nothing is delivered or charged.

import { Honkio } from '@honkio/node'

const honkio = new Honkio(process.env.HONKIO_API_KEY)

const { data, error } = await honkio.messages.send({
  from: '+1416XXXXXXX', // one of your HonkIO numbers
  to: '+1613XXXXXXX',   // a Canadian number you hold consent for
  body: 'Hello from HonkIO!',
})

if (error) {
  console.error(error.name, error.message) // e.g. NON_CANADIAN_NUMBER
} else {
  console.log(data.id, data.status)
}

new Honkio() with no argument reads HONKIO_API_KEY, and throws if neither is set.

Results and errors

data holds the API's response exactly as sent, in snake_case (scheduled_at, segment_count). On failure, error is { name, message, statusCode, details? }.

details is the API's details when it sent one (validation paths, retry_after, missing template keys). Otherwise it holds whatever the API sent beside the error envelope, such as attempts_remaining on VERIFICATION_INVALID_CODE.

Every error code the API answers with, and what to do about each, is on the Errors page.

Write request fields in camelCase (replyTo, scheduledAt, isCommercial, skipConsentCheck); they are sent as the API's snake_case. Keys inside variables, headers and metadata are yours and are sent exactly as written.

Options and keys

The second argument to new Honkio takes these options: baseUrl, which defaults to https://api.honkio.ca; fetch, which defaults to the global fetch (Node 18 or newer), so pass your own to use a polyfill or to intercept requests; and, from version 0.8.0, maxRetries and maxRetryDelayMs, which set how the client retries (below).

import { Honkio } from '@honkio/node'

const honkio = new Honkio('mk_live_...', {
  baseUrl: 'https://api.honkio.ca', // default
  // default: the global fetch. Pass your own to log or proxy requests:
  fetch: (url, init) => {
    console.log(init?.method ?? 'GET', url)
    return fetch(url, init)
  },
  maxRetries: 2, // default; 0 turns retrying off (from version 0.8.0)
  maxRetryDelayMs: 60_000, // default: the longest single wait, in milliseconds
})

From version 0.8.0, the client retries a refusal that waiting fixes: NUMBER_RATE_LIMITED, CARRIER_THROTTLED and CARRIER_UNAVAILABLE. It waits as long as Retry-After asks, or backs off briefly when the API names no wait. RATE_LIMITED and network errors are retried only on a GET or on a request that carries an Idempotency-Key, and every messages.send, emails.send and batch.send now carries one: yours when you pass idempotencyKey, otherwise one the client makes and keeps for each retry of that call, so a retry cannot send or charge twice. By default it retries twice and never waits more than 60 seconds at a time; a longer wait comes back to you as the error. maxRetries: 0 turns retrying off, and maxRetryDelayMs sets the longest wait, in milliseconds. CARRIER_TIMEOUT is never retried: the message may have gone out.

A key's prefix is its mode: mk_test_ keys simulate everything and never reach the carrier or your balance; mk_live_ keys send for real. Nothing else about calling the SDK changes between them.

Method index

Every method on the client, the REST route it calls, and the page that explains it with examples in Node.js and cURL.

Webhooks

Pass the raw body, not parsed JSON, to webhooks.verify (or the standalone verifyWebhook export). It never throws: a parsed body, a missing secret or missing headers answer invalid_argument, and a bad or stale signature answers invalid_signature.

const webhookSecret = process.env.HONKIO_WEBHOOK_SECRET
if (!webhookSecret) throw new Error('Set HONKIO_WEBHOOK_SECRET')

app.post('/webhooks/honkio', express.raw({ type: 'application/json' }), (req, res) => {
  const { data: event, error } = honkio.webhooks.verify(req.body, req.headers, webhookSecret)
  if (error) return res.status(400).end()
  if (!event.livemode) console.log('test event')
  res.status(200).end()
})

The signature is HMAC-SHA256, hex, over the timestamp and the raw body, sent in X-HonkIO-Signature with X-HonkIO-Timestamp and X-HonkIO-Event. Deliveries older than 300 seconds are refused by default; change it with toleranceSeconds.

A verified event is the envelope: id, type, created, account_id, livemode, data. Deduplicate on id: a failed delivery is retried for about 24 hours, each attempt signed afresh with the same event id.

deliveries(id) lists recent attempts. Events that failed every attempt are dead letters: deadLetters(id) lists them, replay(deadLetterId) sends one again, and discard(deadLetterId) drops it. reactivate(id) re-enables an endpoint the platform disabled.

Pagination

List calls follow one of three shapes. Page based (page, limit, and a meta object with page, limit, total and pages): messages.list and consents.list. Offset based (limit, offset): verify.list. Cursor based (limit, cursor, answering with data, has_more and next_cursor): emails.list, emails.received.list, suppressions.list and templates.list. Everything else, such as phoneNumbers.list and webhooks.list, returns every row in one call.

Python

The honkio package needs Python 3.10 or newer and depends only on httpx. It is typed, and has a synchronous client (Honkio) and an asynchronous one (AsyncHonkio) with the same resources and arguments.

pip install honkio

Create a key as above. Honkio() with no argument reads HONKIO_API_KEY and raises InvalidArgumentError if neither is set. Arguments after the id are keyword-only and named like the API's fields; from is a Python keyword, so it is from_. Leave an argument out to not send it; pass None to send null.

from honkio import ApiError, Honkio

client = Honkio()  # reads HONKIO_API_KEY

try:
    message = client.messages.send(
        from_="+1416XXXXXXX",  # one of your HonkIO numbers
        to="+1613XXXXXXX",     # a Canadian number you hold consent for
        body="Hello from HonkIO!",
        idempotency_key="order-1042",
    )
    print(message["id"], message["status"])
except ApiError as e:
    print(e.code, e.message)  # e.g. NON_CANADIAN_NUMBER

Send an email the same way:

import os

from honkio import Honkio

client = Honkio(os.environ["HONKIO_API_KEY"])

sent = client.emails.send(
    from_="Acme <onboarding@test.honkio.ca>",
    to="delivered@test.honkio.ca",
    subject="Hello from HonkIO",
    html="<p>It works.</p>",
)
print(sent["id"])

The same calls, asynchronously:

import asyncio

from honkio import AsyncHonkio


async def main() -> None:
    async with AsyncHonkio() as client:
        message = await client.messages.send(from_="+1416XXXXXXX", to="+1613XXXXXXX", body="Hi")
        print(message["id"])


asyncio.run(main())

Unlike the Node.js SDK, errors are exceptions. Every API error is a subclass of ApiError, with code, message, status_code and details. No response raises APIConnectionError or APITimeoutError, and a bad argument raises InvalidArgumentError. From version 0.2.0, some refusals are retried before an exception is raised (below).

from honkio import APIConnectionError, ApiError, UnprocessableEntityError

try:
    client.verify.check("VERIFICATION_ID", code="123456")
except UnprocessableEntityError as e:
    print(e.code, e.details)  # e.g. VERIFICATION_INVALID_CODE {"attempts_remaining": 2}
except ApiError as e:
    print(e.status_code, e.code, e.message)
except APIConnectionError:
    ...  # no response arrived (timeouts too): safe to try the check again

From version 0.2.0, Honkio and AsyncHonkio retry NUMBER_RATE_LIMITED, CARRIER_THROTTLED and CARRIER_UNAVAILABLE, waiting as long as Retry-After asks. RATE_LIMITED and connection errors are retried only on a GET or on a request with an idempotency key, and messages.send, emails.send and batch.send always send one: your idempotency_key, or one the client makes and keeps for each retry of that call. The defaults are 2 retries and no single wait over 60 seconds; when retrying does not help, the last exception is raised. max_retries=0 turns retrying off, and max_retry_delay sets the longest wait, in seconds.

from honkio import Honkio

# The defaults (from version 0.2.0): 2 retries, no single wait over 60 seconds.
client = Honkio(max_retries=2, max_retry_delay=60)

# Retrying off: every refusal is raised at once.
no_retries = Honkio(max_retries=0)

Every error code the API answers with, and what to do about each, is on the Errors page.

verify_webhook takes the raw body (str or bytes), the headers and your signing secret. It returns the parsed event, and raises InvalidSignatureError when the signature, the timestamp (more than 300 seconds old) or the body is wrong. Pass the body before any JSON parsing.

import os

from honkio import InvalidSignatureError, verify_webhook

WEBHOOK_SECRET = os.environ["HONKIO_WEBHOOK_SECRET"]


def handle(request):  # a Flask-style request
    try:
        event = verify_webhook(request.get_data(), request.headers, WEBHOOK_SECRET)
    except InvalidSignatureError:
        return "bad signature", 400
    if not event["livemode"]:
        print("test event")
    return "", 204

PHP

honkio/honkio-php needs PHP 8.2 or newer and Guzzle 7. Requests are arrays with the API's own snake_case keys, and responses are decoded arrays. Omit a key to not send it; null sends null.

composer require honkio/honkio-php

Create a key as above. new Honkio() with no argument reads HONKIO_API_KEY and throws InvalidArgumentException if neither is set.

<?php

use Honkio\Exception\ApiException;
use Honkio\Honkio;

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

try {
    $message = $honkio->messages->send([
        'from' => '+1416XXXXXXX', // one of your HonkIO numbers
        'to' => '+1613XXXXXXX',   // a Canadian number you hold consent for
        'body' => 'Hello from HonkIO!',
    ], idempotencyKey: 'order-1042');

    echo $message['id'], ' ', $message['status'], "\n";
} catch (ApiException $e) {
    echo $e->errorCode, ': ', $e->getMessage(), "\n"; // e.g. NON_CANADIAN_NUMBER
}

Send an email the same way:

<?php

use Honkio\Honkio;

$honkio = new Honkio(getenv('HONKIO_API_KEY'));

$email = $honkio->emails->send([
    'from' => 'Acme <onboarding@test.honkio.ca>',
    'to' => 'delivered@test.honkio.ca',
    'subject' => 'Hello from HonkIO',
    'html' => '<p>It works.</p>',
]);
echo $email['id'], "\n";

Errors are exceptions, and each one implements Honkio\Exception\HonkioException. An API error is an ApiException (or the subclass for its status) with errorCode, statusCode, getMessage() and details. No response throws ConnectionException, and the send may or may not have happened. Pass an idempotency key as the last argument of messages->send, emails->send and batch->send, and reuse it when you retry.

<?php

use Honkio\Exception\ApiException;
use Honkio\Exception\ConnectionException;

try {
    $honkio->verify->check('VERIFICATION_ID', ['code' => '123456']);
} catch (ApiException $e) {
    if ($e->errorCode === 'VERIFICATION_INVALID_CODE') {
        echo $e->details['attempts_remaining'];
    }
} catch (ConnectionException $e) {
    // No response arrived: safe to try the check again.
}

From version 0.2.0, the client retries NUMBER_RATE_LIMITED, CARRIER_THROTTLED and CARRIER_UNAVAILABLE, waiting as long as Retry-After asks. RATE_LIMITED and connection errors are retried only on a GET or on a request with an idempotency key, and messages->send, emails->send and batch->send always send one: yours, or one the client makes and keeps for each retry of that call. The defaults are 2 retries and no single wait over 60 seconds; when retrying does not help, the last exception is thrown. In the options array, max_retries => 0 turns retrying off, and max_retry_delay sets the longest wait, in seconds.

<?php

use Honkio\Honkio;

// The defaults (from version 0.2.0): 2 retries, no single wait over 60 seconds.
$honkio = new Honkio(null, ['max_retries' => 2, 'max_retry_delay' => 60]);

// Retrying off: every refusal is thrown at once.
$noRetries = new Honkio(null, ['max_retries' => 0]);

Every error code the API answers with, and what to do about each, is on the Errors page.

Webhook::verify takes the raw body, the headers and your signing secret. It returns the event as an array, and throws SignatureVerificationException when it cannot verify a delivery. Pass the body before any JSON parsing.

<?php

use Honkio\Exception\SignatureVerificationException;
use Honkio\Webhook;

$rawBody = file_get_contents('php://input');

try {
    $event = Webhook::verify($rawBody, getallheaders(), getenv('HONKIO_WEBHOOK_SECRET'));
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    exit;
}

if (! $event['livemode']) {
    error_log('test event');
}
http_response_code(204);

Laravel

honkio/laravel adds a mail transport and an SMS notification channel on top of the PHP SDK. It needs PHP 8.2 or newer and Laravel 12 or 13, and Laravel discovers it automatically.

composer require honkio/laravel

Set your key, and the number notifications send from (HONKIO_BASE_URL is only for pointing at another API host):

HONKIO_API_KEY=mk_test_...
HONKIO_SMS_FROM=+14165550100
# MAIL_MAILER=honkio

From version 0.2.0, HONKIO_MAX_RETRIES (default 2; 0 turns retrying off) and HONKIO_MAX_RETRY_DELAY (seconds, default 60) set the client’s retries, as for the PHP SDK.

# The defaults, from version 0.2.0
HONKIO_MAX_RETRIES=2
HONKIO_MAX_RETRY_DELAY=60

Add a mailer to config/mail.php, then set MAIL_MAILER=honkio or call Mail::mailer('honkio'). The from address must belong to a verified sending domain on your account.

<?php

// config/mail.php
return [
    'mailers' => [
        'honkio' => ['transport' => 'honkio'],
    ],
];

Email is transactional by default. Mark a Mailable commercial with the X-HonkIO-Commercial header: the transport removes it and sends is_commercial as true, and the API then requires CASL consent on file and one recipient per message. A refusal throws the SDK exception from Mail::send(). Retries of queued mail are not deduplicated, so a retried job can send again.

<?php

use Illuminate\Mail\Mailable;
use Symfony\Component\Mime\Email;

class SpringSale extends Mailable
{
    public function build(): static
    {
        return $this
            ->subject('Spring sale')
            ->view('mail.spring-sale')
            ->withSymfonyMessage(fn (Email $message) => $message->getHeaders()->addTextHeader('X-HonkIO-Commercial', 'true'));
    }
}

An SMS notification uses the honkio channel and returns a HonkioMessage from toHonkio. The recipient's number (E.164) comes from routeNotificationForHonkio on the notifiable, and a notifiable with no number is skipped without calling the API. Every recipient needs consent on file under CASL. Notifications carry an idempotency key, so a retried queued job cannot send or charge twice.

<?php

use Honkio\Laravel\Notifications\HonkioMessage;
use Illuminate\Notifications\Notification;

class ShipmentSent extends Notification
{
    public function via($notifiable): array
    {
        return ['honkio'];
    }

    public function toHonkio($notifiable): HonkioMessage
    {
        return HonkioMessage::create('Your order has shipped.')
            ->from('+14165550100'); // optional, defaults to HONKIO_SMS_FROM
    }
}

<?php

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    // The recipient's number, in E.164. A user with none is skipped without calling the API.
    public function routeNotificationForHonkio($notification): ?string
    {
        return $this->phone_number;
    }
}

The client is also available as the Honkio facade (Honkio::messages()->send([...])) and, as a singleton, by type-hinting Honkio\Honkio.