@kubiks/otel-inbound

OpenTelemetry instrumentation for the Inbound email API SDK. Capture spans for every Inbound API operation, enrich them with detailed metadata, and monitor your complete email workflow from traces.

Visualize your email operations with detailed span information including recipients, subjects, scheduling, and webhook processing.

Installation

npm install @kubiks/otel-inbound
# or
pnpm add @kubiks/otel-inbound

Peer Dependencies: @opentelemetry/api >= 1.9.0, @inboundemail/sdk >= 4.0.0

Quick Start

import { Inbound } from "@inboundemail/sdk";
import { instrumentInbound } from "@kubiks/otel-inbound";

const inbound = instrumentInbound(new Inbound(process.env.INBOUND_API_KEY!));

await inbound.emails.send({
  from: "[email protected]",
  to: ["[email protected]"],
  subject: "Welcome",
  html: "<p>Hello world</p>",
});

instrumentInbound wraps the instance you already use — no configuration changes needed. Every SDK call creates a client span with useful attributes.

What Gets Traced

This instrumentation wraps all Inbound API operations, creating spans for each:

Email Operations

• emails.send() - Send email
• emails.schedule() - Schedule email for later delivery
• emails.reply() - Reply to an existing email thread
• emails.retrieve() - Retrieve email details
• emails.listScheduled() - List scheduled emails
• emails.getScheduled() - Get specific scheduled email
• emails.cancelScheduled() - Cancel a scheduled email

Management Operations

• Endpoints: list(), create(), get(), update(), delete()
• Addresses: list(), create(), get(), update(), delete()
• Domains: list(), create(), get(), update(), delete(), getDNS()

Thread & Attachment Operations

• Threads: list(), get(), actions(), statistics()
• Attachments: download()

Webhook Receivers

• Incoming email webhooks (via instrumentInboundWebhook)

Span Attributes

Each span includes relevant attributes based on the operation type:

Base Attributes (All Operations)

| Attribute | Description | Example | | ----------------------- | ---------------------------- | ------------------------ | | messaging.system | Constant value inbound | inbound | | messaging.operation | Operation type | send, schedule, etc. | | inbound.resource | Resource being accessed | emails, endpoints | | inbound.target | Full operation target | emails.send |

Email Attributes

| Attribute | Description | Example | | --------------------------- | --------------------------------- | --------------------------------------- | | inbound.message_id | Message ID returned by Inbound | msg_123 | | inbound.to_addresses | Comma-separated TO addresses | [email protected], [email protected] | | inbound.cc_addresses | Comma-separated CC addresses | [email protected] | | inbound.bcc_addresses | Comma-separated BCC addresses | [email protected] | | inbound.recipient_count | Total number of recipients | 3 | | inbound.from | Sender email address | [email protected] | | inbound.subject | Email subject line | Welcome to our service | | inbound.html_content | HTML content (if capture enabled) | <p>Hello</p> | | inbound.text_content | Text content (if capture enabled) | Hello |

Scheduling Attributes

| Attribute | Description | Example | | ----------------------- | ---------------------------- | ------------------------ | | inbound.scheduled_at | Scheduled delivery time | 2025-01-01T00:00:00Z | | inbound.schedule_id | Schedule ID from API | sched_123 |

Management Attributes

| Attribute | Description | Example | | ---------------------- | ------------------------- | ------------ | | inbound.endpoint_id | Endpoint identifier | ep_123 | | inbound.domain_id | Domain identifier | dom_123 | | inbound.address_id | Email address identifier | addr_123 |

Thread & Attachment Attributes

| Attribute | Description | Example | | ------------------------ | -------------------------- | -------------- | | inbound.thread_id | Email thread identifier | thread_123 | | inbound.attachment_id | Attachment identifier | attach_123 |

Webhook Attributes

| Attribute | Description | Example | | ---------------------- | ------------------------------ | ---------------- | | inbound.webhook_id | Webhook identifier from header | webhook_123 | | http.status_code | HTTP response status code | 200 |

Advanced Usage

Webhook Receiver Instrumentation

Instrument Next.js route handlers that receive incoming emails:

import { instrumentInboundWebhook } from "@kubiks/otel-inbound";

export const POST = instrumentInboundWebhook(async (request: Request) => {
  const email = await request.json();
  
  // Process incoming email
  console.log('Received email from:', email.from);
  console.log('Subject:', email.subject);
  
  // Your email processing logic here
  await processIncomingEmail(email);
  
  return Response.json({ success: true });
});

This creates SERVER spans (SpanKind.SERVER) that automatically capture:

• Email metadata from webhook payload
• Webhook headers
• Response status
• Any errors during processing

Configuration Options

Control what data is captured in your spans:

import { instrumentInbound, type InstrumentInboundConfig } from "@kubiks/otel-inbound";

const config: InstrumentInboundConfig = {
  // Capture email HTML/text content in spans (default: false)
  captureEmailContent: true,
  
  // Maximum content length before truncation (default: 1024)
  maxContentLength: 2048,
};

const inbound = instrumentInbound(
  new Inbound(process.env.INBOUND_API_KEY!),
  config
);

Note: Be cautious when enabling captureEmailContent as it may capture sensitive information in your traces.

Scheduling Emails

await inbound.emails.schedule({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Scheduled Newsletter",
  html: "<p>Weekly update</p>",
  scheduledAt: "2025-01-01T09:00:00Z",
});

// List all scheduled emails
const scheduled = await inbound.emails.listScheduled();

// Cancel a scheduled email
await inbound.emails.cancelScheduled("sched_123");

Reply to Emails

await inbound.emails.reply({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Re: Support Request",
  html: "<p>Thanks for reaching out!</p>",
  threadId: "thread_123", // Thread ID from webhook payload
});

Domain Management

// Create a domain
const domain = await inbound.domains.create({
  domain: "yourdomain.com",
});

// Get DNS records for verification
const dns = await inbound.domains.getDNS(domain.data.id);
console.log("Add these DNS records:", dns.data.records);

// List all domains
const domains = await inbound.domains.list();

Endpoint Management

// Create webhook endpoint
const endpoint = await inbound.endpoints.create({
  url: "https://yourdomain.com/webhook",
  events: ["email.received"],
});

// Update endpoint
await inbound.endpoints.update(endpoint.data.id, {
  url: "https://yourdomain.com/new-webhook",
});

// Delete endpoint
await inbound.endpoints.delete(endpoint.data.id);

Complete Example with Webhook

import { Inbound } from "@inboundemail/sdk";
import { instrumentInbound, instrumentInboundWebhook } from "@kubiks/otel-inbound";

// Instrument the Inbound client
const inbound = instrumentInbound(
  new Inbound(process.env.INBOUND_API_KEY!),
  { captureEmailContent: true }
);

// Send an email
await inbound.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome!",
  html: "<p>Thanks for signing up!</p>",
});

// Webhook handler for receiving emails
export const POST = instrumentInboundWebhook(
  async (request: Request) => {
    const email = await request.json();
    
    // Automatically reply to incoming emails
    await inbound.emails.reply({
      from: email.to,
      to: email.from,
      subject: `Re: ${email.subject}`,
      html: "<p>Thanks for your email! We'll get back to you soon.</p>",
      threadId: email.threadId,
    });
    
    return Response.json({ processed: true });
  },
  { captureEmailContent: true }
);

License

MIT