/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.

Primary LanguageTypeScriptMIT LicenseMIT

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