@inbounter/server

Official server-side SDK for Inbounter - the inbound message routing platform.

Installation

npm install @inbounter/server
# or
yarn add @inbounter/server
# or
pnpm add @inbounter/server

Quick Start

import { Inbounter, WebhookEvent } from "@inbounter/server";

const inbounter = new Inbounter("your-api-key");

// Set workspace for workspace-scoped operations
inbounter.setWorkspaceId("wks_abc123");

// Create a webhook
const webhook = await inbounter.webhooks.create({
  url: "https://example.com/webhook",
  events: [WebhookEvent.CONTACT_CREATED, WebhookEvent.CONTACT_UPDATED],
});

// Create an inbound email source
const source = await inbounter.sources.create({
  type: "EMAIL",
  address: "[email protected]",
  name: "Support Inbox",
});

Usage with Next.js

Server Actions

// app/actions.ts
"use server";

import { Inbounter, WebhookEvent } from "@inbounter/server";

const inbounter = new Inbounter(process.env.INBOUNTER_API_KEY!);
inbounter.setWorkspaceId(process.env.INBOUNTER_WORKSPACE_ID!);

export async function createWebhook(url: string) {
  return await inbounter.webhooks.create({
    url,
    events: [WebhookEvent.CONTACT_CREATED],
  });
}

API Routes

// app/api/webhooks/route.ts
import { Inbounter } from "@inbounter/server";
import { NextRequest, NextResponse } from "next/server";

const inbounter = new Inbounter(process.env.INBOUNTER_API_KEY!);

export async function POST(request: NextRequest) {
  const { url, events } = await request.json();

  const webhook = await inbounter.webhooks.create({
    url,
    events,
  });

  return NextResponse.json({ webhook });
}

API Reference

Webhooks

Manage webhook subscriptions for receiving real-time events.

// Create a webhook
const webhook = await inbounter.webhooks.create({
  url: "https://example.com/webhooks/contacts",
  events: ["CONTACT_CREATED", "CONTACT_UPDATED"],
  token: "optional-secret-token", // Optional: auto-generated if not provided
});

// Get a webhook
const webhook = await inbounter.webhooks.get("webhook-id");

// Update a webhook
const updated = await inbounter.webhooks.update("webhook-id", {
  events: ["CONTACT_CREATED"],
  status: "ACTIVE",
});

// List webhooks
const { items, cursor, hasMore } = await inbounter.webhooks.list({
  limit: 20,
  status: "ACTIVE",
});

// Pause a webhook
await inbounter.webhooks.pause("webhook-id", "Maintenance");

// Resume a webhook
await inbounter.webhooks.resume("webhook-id");

// Test a webhook
const result = await inbounter.webhooks.test("webhook-id");

// Delete a webhook
await inbounter.webhooks.delete("webhook-id");

Webhook Events

| Event | Description | |-------|-------------| | CONTACT_CREATED | A new contact was created | | CONTACT_UPDATED | A contact was updated | | CONTACT_DELETED | A contact was deleted | | CONTACT_PROPERTY_UPDATED | A contact property was updated | | CONTACT_TAG_ADDED | A tag was added to a contact | | CONTACT_TAG_REMOVED | A tag was removed from a contact | | CONTACT_SUBSCRIBED | A contact subscribed | | CONTACT_UNSUBSCRIBED | A contact unsubscribed | | CONTACT_RESUBSCRIBED | A contact resubscribed | | WORKSPACE_BANNED | Workspace was banned | | WORKSPACE_SENDING_EMAILS_PAUSED | Email sending was paused | | WORKSPACE_TEAM_MEMBER_JOINED | A team member joined | | TESTING_CONNECTION | Test webhook event |

Sources (Inbound Email/SMS)

Manage inbound message sources for receiving emails and SMS.

// Set workspace ID first
inbounter.setWorkspaceId("wks_abc123");

// Create an email source
const source = await inbounter.sources.create({
  type: "EMAIL",
  address: "[email protected]",
  name: "Support Inbox",
  settings: {
    autoReply: {
      enabled: true,
      message: "Thanks for reaching out! We'll respond shortly.",
    },
  },
});

// Get a source
const source = await inbounter.sources.get("source-id");

// Update a source
const updated = await inbounter.sources.update("source-id", {
  name: "Updated Name",
  settings: {
    autoReply: { enabled: false },
  },
});

// List sources
const { items, cursor, hasMore } = await inbounter.sources.list({
  type: "EMAIL",
  status: "ACTIVE",
});

// Verify a source (check DNS records)
const verified = await inbounter.sources.verify("source-id");

// Delete a source
await inbounter.sources.delete("source-id");

Messages

Access inbound messages received by your sources.

// Set workspace ID first
inbounter.setWorkspaceId("wks_abc123");

// Get a specific message with full details (route runs + deliveries)
const { message, routeRuns, deliveries } = await inbounter.messages.get("message-id");

// List messages by source
const { items, cursor, hasMore } = await inbounter.messages.listBySource(
  "source-id",
  {
    limit: 20,
    status: "DELIVERED",
  }
);

// List all messages in workspace
const messages = await inbounter.messages.list({
  startDate: "2024-01-01",
  endDate: "2024-01-31",
});

// Retry a specific failed delivery
// First, get the message details to find the failed delivery
const details = await inbounter.messages.get("message-id");
const failedDelivery = details.deliveries.find(d => d.status === "FAILED");
if (failedDelivery) {
  await inbounter.messages.retryDelivery("message-id", failedDelivery.id);
}

Configuration

const inbounter = new Inbounter("your-api-key", {
  baseUrl: "https://api.inbounter.com", // default
  timeout: 30000, // 30 seconds
  maxRetries: 3,
  apiVersion: "v1",
});

// Set workspace ID for workspace-scoped operations
inbounter.setWorkspaceId("wks_abc123");

// Enable debug mode
inbounter.setDebugMode(true);

// Set custom headers
inbounter.setHeader("X-Custom-Header", "value");

Error Handling

import {
  Inbounter,
  InbounterError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from "@inbounter/server";

try {
  await inbounter.webhooks.create({ url: "invalid" });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof ValidationError) {
    console.error("Validation error:", error.message);
  } else if (error instanceof InbounterError) {
    console.error("API error:", error.message, error.code);
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions:

import type {
  // Webhooks
  Webhook,
  WebhookCreateOptions,
  WebhookEvent,
  WebhookStatus,
  // Sources
  Source,
  SourceType,
  SourceStatus,
  // Messages
  Message,
  MessageStatus,
  EmailPayload,
  SmsPayload,
} from "@inbounter/server";

Singleton Pattern

For convenience, you can also use the singleton pattern:

import { init, getClient } from "@inbounter/server";

// Initialize once (e.g., in your app's entry point)
init("your-api-key", { timeout: 60000 });

// Use anywhere in your app
const client = getClient();
await client.webhooks.list();

License

MIT