email-octopus-ts

email-octopus-ts is an unofficial TypeScript library for sending emails with the Email Octopus API. The API also supports many other features like managing lists and contacts.

Fully typed, works out of the box with TypeScript
Automatic pagination
Improved error handling

Who uses email-octopus-ts?

tooltipr - Demystify your corporate jargon. tooltipr helps you and your colleagues to actually understand acronyms.
hackathon.camp - Organize your hackathons the easy way. We help you organize and manage your hackathons to save up to 90% of the time you would spend on organizing.

Installation

The package is published on npm as email-octopus-ts. You will have to install axios because this package depends on it.

Using yarn

yarn add axios email-octopus-ts

Using npm

npm install axios email-octopus-ts

Usage

First, we need to initialize the client with the constructor:

import { emailOctopus } from "email-octopus-ts";

// TODO: Replace the API key.
const emailOctopusApiKey = "...";
const EmailOctopus = emailOctopus(emailOctopusApiKey);

After that we can call the API methods:

EmailOctopus.lists.createContact

import { emailOctopus } from "email-octopus-ts";

// TODO: Replace the API key.
const emailOctopusApiKey = "...";
const EmailOctopus = emailOctopus(emailOctopusApiKey);

const contact = await EmailOctopus.lists.createContact({
  listId: "...",
  emailAddress: "hello@hackathon.camp",
  // fields?: Record<string, unknown>;
  // tags?: Array<string>;
  // status?: "SUBSCRIBED" | "UNSUBSCRIBED" | "PENDING";
});

// Contact is of type:
// ---
// id: string;
// email_address: string;
// fields: Record<string, unknown>;
// tags: Array<string>;
// status: "SUBSCRIBED" | "UNSUBSCRIBED" | "PENDING";
// created_at: string;
console.log({ contact });

EmailOctopus.lists.getAllContacts

import { emailOctopus } from "email-octopus-ts";

// TODO: Replace the API key.
const emailOctopusApiKey = "...";
const EmailOctopus = emailOctopus(emailOctopusApiKey);

const contacts = await EmailOctopus.lists.getAllContacts(
  {
    listId: "...",
    // limit?: number;
    // page?: number;
  },
  {
    // Will loop through all pages
    autoPaginate: true,
  },
);

contacts.forEach((contact) => {
  // Contact is of type:
  // ---
  // id: string;
  // email_address: string;
  // fields: Record<string, unknown>;
  // tags: Array<string>;
  // status: "SUBSCRIBED" | "UNSUBSCRIBED" | "PENDING";
  // created_at: string;
  console.log({ contact });
});

Why Email Octopus?

Email Octopus is a service that helps you manage your email lists. It is a powerful tool that can be used to manage your email lists, send emails, and track your email opens.

I am a indie hacker and I am using Email Octopus for several side projects because it is:

cheap
reliable
support is always there

Why this library?

First library with TypeScript support
Improved error handling
Automatic pagination so you don't have to implement it yourself

Licence

MIT