@anymail/sdk (TypeScript/JavaScript)

Official TypeScript/JavaScript client for the AnyMail Developer API (/api/v1).

src/generated/types.ts is generated fresh from ../openapi.json by openapi-typescript - see ../scripts/generate-spec.ts and ../README.md. src/client.ts, src/webhooks.ts, and src/index.ts are the hand-written files in this package.

Install

npm install @anymail/sdk

Self-hosted alternative

If you'd rather install straight from an AnyMail deployment instead of npm (or npm publishing isn't turned on for this deployment yet - see ../README.md "Publishing"), npm can install directly from a tarball URL - no filename-detection trick needed here, unlike pip:

npm install https://anymail.tech/api/sdk-artifacts/typescript

Usage

import { AnyMailClient, unwrapOrThrow } from '@anymail/sdk';

const client = new AnyMailClient({ apiKey: 'am_...' }); // baseUrl defaults to https://anymail.tech/api/v1

// Full type inference for every endpoint via client.api (openapi-fetch), no per-endpoint code:
const { data, error } = await client.api.GET('/mail-servers/{id}', { params: { path: { id: 'ms_...' } } });

// Or throw-on-error, matching AnyMail's own {code, message} error contract:
const { user } = unwrapOrThrow(await client.api.GET('/me'));

const { message } = unwrapOrThrow(
  await client.api.POST('/inboxes/{id}/messages', {
    params: { path: { id: 'inb_...' } },
    body: { to: '[email protected]', subject: 'Hi', body: 'Hello!' }
  })
);

client.api is a real openapi-fetch client typed against the generated paths - every Developer API endpoint (including ones added after this README was written) is reachable through it with full type inference. unwrapOrThrow is a small, generic helper (not tied to any one endpoint) that turns a {data, error} result into data, or throws AnyMailApiError carrying the server's status/code/message/details.

Webhook signature verification

import { verifyWebhookSignature } from '@anymail/sdk';

if (!verifyWebhookSignature(rawBody, req.headers['x-anymail-signature'], webhookSecret)) {
  return res.status(400).end();
}

rawBody must be the exact string of the received request body, read before any JSON parsing - see the function's docstring. Node-only (uses node:crypto), which is fine since webhook verification always runs on the receiving server, never in a browser. This helper is unrelated to client.api and works even if you're not otherwise using this SDK to call the API.

Regenerating

See ../README.md "Regenerating locally".