@airhornjs/twilio

Twilio SMS and SendGrid Email provider for the Airhorn notification system.

How to Contribute
Licensing and Copyright

Installation

npm install airhorn @airhornjs/twilio

Features

SMS sending via Twilio API
Email sending via SendGrid API
Automatic error handling and retry support
Integration with Airhorn's notification system

Usage

SMS with Twilio

import { Airhorn, AirhornSendType } from 'airhorn';
import { AirhornTwilio } from '@airhornjs/twilio';

// Create Twilio provider for SMS only
const twilioProvider = new AirhornTwilio({
  accountSid: 'your-account-sid',
  authToken: 'your-auth-token',
});

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

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(
  '+0987654321', // to
  template,
  data,
  AirhornSendType.SMS,
  { from: '+1234567890' }, // your Twilio phone number
);

Email with SendGrid

import { Airhorn, AirhornSendType } from 'airhorn';
import { AirhornTwilio } from '@airhornjs/twilio';

// Create Twilio provider with SendGrid support
const twilioProvider = new AirhornTwilio({
  accountSid: 'your-account-sid',
  authToken: 'your-auth-token',
  sendGridApiKey: 'your-sendgrid-api-key', // Enables email support
});

// Create Airhorn instance
const airhorn = new Airhorn({
  providers: [twilioProvider],
});

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

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

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

The sender can also be set on the template itself (template.from) — options.from on the send call takes precedence.

Both SMS and Email

When configured with both Twilio and SendGrid credentials, the provider supports both SMS and email notifications:

const provider = new AirhornTwilio({
  // Twilio SMS configuration
  accountSid: 'your-account-sid',
  authToken: 'your-auth-token',
  
  // SendGrid Email configuration
  sendGridApiKey: 'your-sendgrid-api-key',
  
  // Optional Twilio configuration
  region: 'sydney',
  edge: 'sydney',
});

// Provider capabilities will include both 'sms' and 'email'
console.log(provider.capabilities); // ['sms', 'email']

Configuration

AirhornTwilioOptions

accountSid (required): Your Twilio Account SID
authToken (required): Your Twilio Auth Token
sendGridApiKey (optional): Your SendGrid API key (enables email support)
region (optional): Twilio region
edge (optional): Twilio edge location

Additional Options

For provider-specific options, call the provider directly with a message — the second parameter is passed through to Twilio / SendGrid:

Twilio SMS Options

await twilioProvider.send(message, {
  statusCallback: 'https://example.com/callback',
  maxPrice: '0.50',
  validityPeriod: 14400,
  // ... other Twilio message options
});

SendGrid Email Options

await twilioProvider.send(message, {
  replyTo: '[email protected]',
  categories: ['transactional', 'order-confirmation'],
  trackingSettings: {
    clickTracking: { enable: true },
    openTracking: { enable: true },
  },
  // ... other SendGrid mail options
});

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.