GroundhoggClient

A lightweight TypeScript client for interacting with the Groundhogg v4 REST API. Easily manage contacts, tags, and send transactional or marketing emails via API.

Features

• ✅ Create, fetch, update, and delete contacts
• 🏷️ Add or remove tags by email
• 📩 Send transactional or marketing emails
• 🌱 Fully typed with TypeScript
• 🧪 Tested with Vitest

Installation

# With pnpm
pnpm add groundhogg-js

# Or with npm
npm install groundhogg-js

# Or with yarn
yarn add groundhogg-js

Usage

import { GroundhoggClient } from "groundhogg-client";
import dotenv from "dotenv";

dotenv.config();

const gh = new GroundhoggClient({
  baseUrl: process.env.GROUNDHOGG_API_URI!,
  publicKey: process.env.GROUNDHOGG_PUBLIC_KEY!,
  token: process.env.GROUNDHOGG_TOKEN!,
  defaultFrom: "[email protected]",
});

Create Contact

await gh.createContact({
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe",
  tags: [123, "newsletter"],
});

Get Contact

const contact = await gh.getContact("[email protected]");
console.log(contact);

Add or Remove Tags

await gh.addOrRemoveTags({
  email: "[email protected]",
  addTags: ["customer"],
  removeTags: [123],
});

Delete Contact

await gh.deleteContact("[email protected]");

Send Email

await gh.sendEmail({
  to: ["[email protected]"],
  subject: "Welcome!",
  fromEmail: "[email protected]",
  fromName: "Your Team",
  type: "transactional",
  content: "<p>Thanks for joining!</p>",
});

Environment Variables

The client expects the following environment variables (or pass them directly):

GROUNDHOGG_API_URI=https://yourdomain.com
GROUNDHOGG_PUBLIC_KEY=your-public-key
GROUNDHOGG_TOKEN=your-token

License

MIT © Parth Koshti