Skip to main content
📦 View on npm

​
Installation

Install the AI Inbx TypeScript SDK using your preferred package manager: 
npm install aiinbx

​
Quick Start

Initialize the client with your API key: 
import AIInbx from 'aiinbx';

// If using the default environment variable AI_INBX_API_KEY
const aiInbx = new AIInbx();

// Or explicitly pass your API key
// const aiInbx = new AIInbx({
//   apiKey: 'your-api-key-here',
// });

// Search threads
const response = await aiInbx.threads.search({});
console.log(response.threads);

const newestThread = response.threads[0];
const newestEmail = newestThread.emails[0];

// Reply to an email
await aiInbx.emails.reply(newestEmail.id, {
  from: "your-domain@example.com",
  html: "<p>This is a test reply email</p>"
});

​
Built-in Helpers

​
1. Next.js webhook handler

createNextRouteHandler() generates a ready-to-use POST handler that:
  • Validates the request signature using the AI_INBX_SECRET env variable.
  • Parses the webhook payload and routes it to the correct callback.
  1. Add an API route (any path works, e.g., app/api/aiinbx-webhook/route.ts): 
    import { createNextRouteHandler } from 'aiinbx/helpers';

export const POST = createNextRouteHandler({
  onInboundEmail: async ({ payload, isVerified }) => {
    const { email } = payload.data;

    console.log('Inbound email', { email, isVerified });
    return Response.json({ ok: true });
  },
});
  2. Set AI_INBX_SECRET in your environment. The value is shown once when you enable secrets during webhook creation.
    • Secret on/off can’t be toggled later—delete & recreate the webhook to change.
    • Lost or exposed the secret? Click Rotate secret in the webhook dropdown to generate a fresh value and invalidate the old one.
  3. Add the webhook URL (/api/aiinbx-webhook) in the dashboard.

​
Handler parameters

​
2. LLM-friendly formatting

Use emailToLLMString() and threadToLLMString() to transform rich email objects into compact, XML-ish strings optimised for Large Language Models: 
import {
  emailToLLMString,
  threadToLLMString,
} from 'aiinbx/helpers';

const emailPrompt = emailToLLMString(email);
const threadPrompt = threadToLLMString(thread);
These helpers:
  • Keep only fields relevant for reasoning (addresses, subject, text, etc.).
  • Preserve structure with lightweight XML-like tags.
  • Return a single string ready to drop into your prompts.

​
Full example: AI-powered support bot

app/api/aiinbx-webhook/route.ts
import { openai } from '@ai-sdk/openai';
import { generateObject } from 'ai';
import { z } from 'zod';
import AIInbx from 'aiinbx';
import {
  createNextRouteHandler,
  emailToLLMString,
  threadToLLMString,
} from 'aiinbx/helpers';

const aiInbx = new AIInbx();

export const POST = createNextRouteHandler({
  onInboundEmail: async ({ payload }) => {
    const { email } = payload.data;
    const thread = await aiInbx.threads.retrieve(email.threadId);

    const { object } = await generateObject({
      model: openai('gpt-4.1-mini'),
      schema: z.object({
        responseHtml: z.string(),
      }),
      system: `You are a helpful assistant that can gets incoming emails and should answer them as a human would.`,
      prompt: `Here are the emails so far: ${threadToLLMString(thread)}

Here is the new email: ${emailToLLMString(email)}

Please answer the email as a human would.`,
    });

    await aiInbx.emails.reply(email.id, {
      from: 'support@your-domain.com',
      html: object.responseHtml,
    });

    return Response.json({ sent: true });
  },
});
ℹ️ The example above is completely serverless and needs no additional infrastructure.

​
Complete Documentation

For comprehensive documentation including:
  • Request & response types
  • Error handling
  • Advanced configuration
  • All available methods
  • TypeScript examples
Visit the complete TypeScript SDK documentation on npm.