EmailOctopus API Client

Type-safe SDK for the EmailOctopus REST API v2, generated with @hey-api/openapi-ts. The package wraps the official OpenAPI schema and exposes fully typed helpers for every endpoint.

The published package name is emailoctopus-api-client.

Installation

pnpm add emailoctopus-api-client
# or
npm install emailoctopus-api-client
# or
yarn add emailoctopus-api-client

Quick Start

import { apiListsListIdcontactsPost } from "emailoctopus-api-client";

const clientOptions = {
  auth: process.env.EMAILOCTOPUS_API_KEY,
};

async function subscribeContact(listId: string) {
  const result = await apiListsListIdcontactsPost({
    path: { list_id: listId },
    auth: clientOptions.auth,
    body: {
      email_address: "[email protected]",
      fields: {
        FirstName: "Ada",
      },
      status: "SUBSCRIBED",
    },
  });

  if (result.error) {
    console.error(result.error);
    return;
  }

  console.log(result.data);
}

subscribeContact("your-list-id");

Response Handling Modes

Each generated helper returns { data, error, request, response } by default. Set throwOnError to true to raise errors instead, or responseStyle: 'data' to unwrap the data:

const { data } = await apiCampaignsGet({
  auth: process.env.EMAILOCTOPUS_API_KEY,
  throwOnError: true,
});

Advanced contributors can reuse configuration by importing the generated client utilities from src/client/. The published package currently exposes typed endpoint helpers only.

Available Endpoints

Every OpenAPI endpoint has a matching exported function under src/sdk.gen.ts. Examples:

• apiCampaignsGet – list campaigns
• apiListsListIdcontactsPost – create a contact
• apiAutomationsAutomationIdqueuePost – trigger an automation for a contact

Refer to the official documentation or inspect src/sdk.gen.ts for the full list and parameter typings.

Configuration Reference

All helper functions share a common options object:

• auth: API key or async getter. Required for authenticated endpoints (EmailOctopus uses Bearer tokens).
• path: path parameters object, e.g. { list_id: '123' }.
• query: query parameters object.
• body: request payload. Typed per endpoint.
• headers: additional headers merged with defaults.
• client: pass a custom client instance as shown above.
• throwOnError: when true, rejected promises are thrown instead of returned in { error }.
• responseStyle: set to 'data' to receive only response data.

Regenerating the SDK

The SDK is produced from the public OpenAPI schema. Update generated code after schema changes:

pnpm install
pnpm run generate
pnpm run build

Generation settings live in openapi-ts.config.ts. Regeneration overwrites everything under src/ marked as generated—avoid manual edits to those files.

Development

• pnpm run build – clean, regenerate, and compile to dist/
• pnpm run generate – only refresh generated sources
• pnpm run clean – remove build artifacts

Publishing

Build the package before publishing to ensure dist/ is up to date:

pnpm run build
pnpm publish --access public

Contributing

1. Fork and clone the repo.
2. Install dependencies with pnpm install.
3. Regenerate the SDK if you changed the OpenAPI config.
4. Submit a PR with a clear summary of your changes.

Please open issues for schema mismatches or endpoint coverage gaps.

License

MIT © 2025 spookyuser