@ferrypost/sdk

TypeScript SDK for the Ferry Post messaging API.

Supports iMessage, SMS, and Telegram through a single unified interface. Works in Node.js, Deno, Bun, and edge runtimes.

Installation

npm install @ferrypost/sdk

Quick start

import { MessagingClient } from '@ferrypost/sdk';

const client = new MessagingClient({
  apiKey: 'msgk_live_your_api_key_here',
});

// Send a message
const message = await client.messages.send({
  conversation_id: 'conv_123',
  content: { text: 'Hello from the SDK!' },
});

// List conversations
const page = await client.conversations.list();
console.log(page.data);

Resources

The client exposes 13 resource classes:

| Resource | Description | |---|---| | client.messages | Send, list, edit, unsend, and react to messages | | client.conversations | Create and manage conversations | | client.webhooks | Manage webhook subscriptions and deliveries | | client.scheduledMessages | Create, update, and cancel scheduled messages | | client.phoneNumbers | List and inspect phone numbers | | client.optOuts | List opt-outs and add manual entries | | client.channels | List channels and query capabilities | | client.organization | Manage organization settings and members | | client.apiKeys | Manage API keys | | client.media | Upload and retrieve media attachments | | client.search | Search messages by text or semantic query | | client.analytics | Get usage analytics | | client.telegramAccounts | Connect, list, and manage Telegram accounts |

Sending files

// Upload from a local file
const msg = await client.messages.sendFile('conv_123', '/path/to/photo.jpg', {
  content: { text: 'Check this out' },
});

// Send from a URL (server-side fetch)
const msg = await client.messages.sendFileFromUrl('conv_123', 'https://example.com/image.png');

Webhook verification

Verify incoming webhook signatures without instantiating a client:

import { MessagingClient } from '@ferrypost/sdk';

const isValid = MessagingClient.webhooks.verify(
  rawBody,
  signatureHeader,
  webhookSecret,
);

Configuration

const client = new MessagingClient({
  apiKey: 'msgk_live_...',       // Required
  baseUrl: 'https://ferrypost.com', // Default
  timeout: 30000,                // Request timeout in ms
  maxRetries: 2,                 // Retries for idempotent requests
});

ESM and CommonJS

The SDK ships both ESM and CJS builds. Import or require works out of the box:

// ESM
import { MessagingClient } from '@ferrypost/sdk';

// CJS
const { MessagingClient } = require('@ferrypost/sdk');

Documentation

Full API documentation is available at docs.ferrypost.com.

License

MIT