Adapter Overview

Provider integrations that implement the shared Postbote adapter contract.

An adapter has a stable name and a send(message, options?) method. It receives a normalized EmailMessage, forwards the optional AbortSignal, and returns { messageId, provider, raw? }.

Official adapters are available for Resend, Postmark, and SendGrid. Each provider has a native SDK package and a fetch-based HTTP package. All six packages pass the shared adapter contract suite.

Custom adapters

Use defineAdapter() for a provider integration. It validates the adapter name, handles a pre-aborted signal, appends the provider to successful results, rejects empty message IDs, and normalizes unknown errors.

import { defineAdapter } from "@postbote/core";

export const example = (apiKey: string) =>
  defineAdapter({
    name: "example",
    async send(message, { signal }) {
      const response = await fetch("https://api.example.com/send", {
        method: "POST",
        headers: { Authorization: `Bearer ${apiKey}` },
        body: JSON.stringify(message),
        signal,
      });

      return { messageId: response.headers.get("x-message-id")! };
    },
  });

See Write an adapter for error mapping and contract tests.