@airhornjs/pingram

Pingram (formerly NotificationAPI) provider for Airhorn.

How to Contribute
Licensing and Copyright

Installation

npm install airhorn @airhornjs/pingram

Features

SMS sending via the Pingram API
Email sending via the Pingram API
Mobile push notifications via the Pingram API
One API key for all channels — no per-channel infrastructure to configure
Multi-region support (us, eu, ca)
Automatic error handling and integration with Airhorn's notification system

Usage

SMS with Pingram

import { Airhorn, AirhornSendType } from 'airhorn';
import { AirhornPingram } from '@airhornjs/pingram';

// Create Pingram provider
const pingramProvider = new AirhornPingram({
  apiKey: 'pingram_sk_your_api_key',
});

// Create Airhorn instance with Pingram provider
const airhorn = new Airhorn({
  providers: [pingramProvider],
});

const data = {
  orderId: '12345',
  customerName: 'John',
};

// The template is the content of the message
const template = {
  content: 'Hello <%= customerName %>!, your order #<%= orderId %> has been shipped!',
};

// Send SMS — the sender is part of the send call
const result = await airhorn.send(
  '+16175551212', // to (E.164 format)
  template,
  data,
  AirhornSendType.SMS,
  { from: '+1234567890' }, // Optional: your Pingram sender number (defaults to your provisioned number)
);

Email with Pingram

import { Airhorn, AirhornSendType } from 'airhorn';
import { AirhornPingram } from '@airhornjs/pingram';

const pingramProvider = new AirhornPingram({
  apiKey: 'pingram_sk_your_api_key',
});

const airhorn = new Airhorn({
  providers: [pingramProvider],
});

const data = {
  orderId: '656565',
  customerName: 'John',
};

// Send Email
const template = {
  subject: 'Order Confirmation: <%= orderId %>',
  content: 'Hi <%= customerName %>, your order #<%= orderId %> has been confirmed!',
};

const result = await airhorn.send(
  '[email protected]', // to
  template,
  data,
  AirhornSendType.Email,
  { from: '[email protected]' }, // Optional: must be a verified sender in Pingram
);

The sender can also be set on the template itself (template.from) — options.from on the send call takes precedence, and Pingram's sendDefaults fill in when neither is set.

Mobile Push Notifications with Pingram

Pingram delivers mobile push notifications to the device tokens registered for a user, so the to value is the Pingram user identifier. Device tokens are registered through the Pingram client SDKs in your mobile apps.

import { Airhorn, AirhornSendType } from 'airhorn';
import { AirhornPingram } from '@airhornjs/pingram';

const pingramProvider = new AirhornPingram({
  apiKey: 'pingram_sk_your_api_key',
});

const airhorn = new Airhorn({
  providers: [pingramProvider],
});

const data = {
  orderId: '12345',
  customerName: 'John',
};

const template = {
  subject: 'New Order', // Used as the push notification title
  content: 'Hi <%= customerName %>, you have a new order #<%= orderId %>',
};

await airhorn.send(
  'user-123', // Pingram user id with registered push tokens
  template,
  data,
  AirhornSendType.MobilePush,
  { from: 'YourApp' },
);

Custom Capabilities

You can specify which services to enable using the capabilities option:

// SMS only
const smsProvider = new AirhornPingram({
  apiKey: 'pingram_sk_your_api_key',
  capabilities: [AirhornSendType.SMS],
});

// Email only
const emailProvider = new AirhornPingram({
  apiKey: 'pingram_sk_your_api_key',
  capabilities: [AirhornSendType.Email],
});

// All capabilities (explicit)
const allProvider = new AirhornPingram({
  apiKey: 'pingram_sk_your_api_key',
  capabilities: [AirhornSendType.SMS, AirhornSendType.Email, AirhornSendType.MobilePush],
});

Configuration

AirhornPingramOptions

apiKey (required): Your Pingram API key (starts with pingram_sk_)
region (optional): Pingram API region — us (default), eu, or ca
baseUrl (optional): Custom base URL for the Pingram API (overrides region)
notificationType (optional): The Pingram notification type identifier used for sends (defaults to airhorn). Pingram creates the notification type automatically if it does not exist
capabilities (optional): Array of AirhornSendType values to specify which services to enable (defaults to SMS, Email, and MobilePush)
sendDefaults (optional): Typed Pingram request defaults merged into every send request (e.g. templateId, parameters, or channel content defaults like email.senderName and sms.from). Message-derived values take precedence

Send Defaults

Pingram-specific request fields are configured on the provider through sendDefaults, keeping the airhorn.send() surface generic. The defaults are fully typed against the Pingram SDK and merged into every send request beneath the message values, so the message always wins:

const pingramProvider = new AirhornPingram({
  apiKey: 'pingram_sk_your_api_key',
  sendDefaults: {
    templateId: 'my_template',          // Use a specific Pingram template
    parameters: { plan: 'pro' },        // Pingram template merge tags
    sms: { from: '+15550001111' },      // Default SMS sender number
    email: { senderName: 'Acme Corp' }, // Default email sender name
  },
});

For one-off, per-message Pingram options (for example a scheduled delivery), call the provider directly — the second argument is merged into the request last and can override anything:

await pingramProvider.send(message, {
  schedule: '2026-12-25T00:00:00Z',
});

Prerequisites

Create a Pingram account
Get your API key from the Pingram dashboard
For SMS: use the included number or provision your own through Pingram
For Email: verify your sending domain (or use Pingram's shared domain)
For Mobile Push: register device tokens for your users via the Pingram client SDKs

Testing

pnpm test

How to Contribute

Now that you've set up your workspace, you're ready to contribute changes to the airhorn repository you can refer to the CONTRIBUTING guide. If you have any questions please feel free to ask by creating an issue and label it question.