@uninspired/plunk-client

A TypeScript client for the Plunk HTTP API.

Targets the legacy Plunk API at https://api.useplunk.com (/v1/* routes). Self-hosted instances using the same API shape are also supported.

Automatically parses JSON-encoded contact data fields in responses.

Requirements

• A runtime that supports fetch, Buffer and async/await (Node.js >= 18, bun or deno, optionally the browser with a buffer polyfill)

Installation

npm install @uninspired/plunk-client

Usage

Initializing the client

import { PlunkApiClient } from "@uninspired/plunk-client";

const PLUNK_BASE_URL = "https://api.useplunk.com";
const PLUNK_API_KEY = "sk_your_secret_key";

const plunkApiClient = new PlunkApiClient(PLUNK_BASE_URL, PLUNK_API_KEY);

For trackEvent, you can also use a public key (pk_*) instead of your secret key:

const trackClient = new PlunkApiClient(PLUNK_BASE_URL, "pk_your_public_key");

Automations

Track an event

const res = await plunkApiClient.trackEvent({
  event: "signed_up",
  email: "[email protected]",
  subscribed: true,
  data: {
    foo: "bar",
  },
});

Transactional

Send an email

You can provide attachments to the email by providing an array of JavaScript File objects. They will automatically be converted to base64 with the necessary metadata.

const attachment = new File([], "test.txt");

const res = await plunkApiClient.sendEmail({
  to: "[email protected]",
  subject: "Hello",
  body: "Hello, this is a test email.",
  subscribed: true,
  name: "John Doe",
  from: "[email protected]",
  reply: "[email protected]",
  headers: {
    "X-Custom-Header": "Test",
  },
  attachments: [attachment],
});

// Recipient address is on the nested contact object
const recipient = res.emails[0]?.contact.email;

Campaigns

Campaign style accepts "PLUNK" or "HTML". "PLUNK" is sent to the API as "SANS".

Create a campaign

const res = await plunkApiClient.createCampaign({
  subject: "Hello",
  body: "Hello, this is a test email.",
  recipients: ["[email protected]"],
  style: "PLUNK",
});

Send a campaign

await plunkApiClient.sendCampaign("[CAMPAIGN_ID]", {
  live: true, // Should the campaign be sent to the recipients
  delay: 5, // in minutes
});

Update a campaign

const res = await plunkApiClient.updateCampaign("[CAMPAIGN_ID]", {
  subject: "Hello",
  body: "Hello, this is a test email.",
  recipients: ["[email protected]"],
  style: "PLUNK",
});

Delete a campaign

const res = await plunkApiClient.deleteCampaign("[CAMPAIGN_ID]");

Contacts

Get a contact by ID

interface ContactData {
  foo: string;
}

const res = await plunkApiClient.getContactById<ContactData>("[CONTACT_ID]");

Get all contacts

interface ContactData {
  foo: string;
}

const res = await plunkApiClient.getAllContacts<ContactData>();

Get number of contacts

const res = await plunkApiClient.getNumberOfContacts();

Create a contact

interface ContactData {
  foo: string;
}

const res = await plunkApiClient.createContact<ContactData>({
  email: "[email protected]",
  subscribed: true,
  data: {
    foo: "bar",
  },
});

Subscribe a contact

// Subscribe contact by ID
const res = await plunkApiClient.subscribeContact({ id: "[CONTACT_ID]" });

// Subscribe contact by email
const res = await plunkApiClient.subscribeContact({
  email: "[email protected]",
});

Unsubscribe a contact

// Unsubscribe contact by ID
const res = await plunkApiClient.unsubscribeContact({ id: "[CONTACT_ID]" });

// Unsubscribe contact by email
const res = await plunkApiClient.unsubscribeContact({
  email: "[email protected]",
});

Update a contact

interface ContactData {
  foo: string;
}

const res = await plunkApiClient.updateContact<ContactData>({
  id: "[CONTACT_ID]",
  subscribed: true,
  data: { foo: "bar" },
});

Delete a contact

const res = await plunkApiClient.deleteContact({ id: "[CONTACT_ID]" });

Development

Scripts

bun run build      # Build ESM, CJS, and type declarations
bun run typecheck  # Type-check src and tests
bun test           # Run integration tests against the live API

Integration tests

Tests run against the real Plunk API. Copy .env.example to .env and fill in your credentials:

cp .env.example .env

| Variable | Description | | --- | --- | | PLUNK_SECRET_KEY | Secret API key (sk_*) for most endpoints | | PLUNK_PUBLIC_KEY | Public API key (pk_*) for trackEvent tests | | PLUNK_BASE_URL | API base URL (https://api.useplunk.com) | | PLUNK_TEST_EMAIL | Inbox used for send/track tests | | PLUNK_TEST_FROM | Verified sender address for email tests |

Features

Providing types for the arbitrary "data" field

Any request or response that contains a "data" field can have its type enforced by providing a type argument to the respective method.

Note: The data is not validated, it is simply typed.

interface ContactData {
  foo: string;
  bar?: string;
}

const res = await plunkApiClient.getContactById<ContactData>("[CONTACT_ID]");

// res.data will be of type ContactData

This will throw a TypeScript error:

interface ContactData {
  foo: string;
}

const res = await plunkApiClient.trackEvent<ContactData>({
  event: "signed_up",
  email: "[email protected]",
  data: {
    bar: "bar",
  },
});