Guides

SDK and CLI

A typed TypeScript client for Node, Bun, Deno and edge runtimes, and a command-line tool for templates, tests and logs. Both wrap the same REST API.

Install

npm install mailpark

The client reads MAILPARK_API_KEY and MAILPARK_API_URL from the environment, or takes them as options.

import { Mailpark } from "mailpark";

export const mailpark = new Mailpark({
  apiKey: process.env.MAILPARK_API_KEY,
  baseUrl: "https://api.mailpark.io",
});

Option	Default
`apiKey`	`MAILPARK_API_KEY`	Test or live key.
`baseUrl`	`MAILPARK_API_URL`	Falls back to the local API, http://localhost:4000.
`autoIdempotency`	`true`	Add a random Idempotency-Key to every write.
`fetch`	global fetch	Bring your own, for tests or proxies.
`headers`	{}	Extra headers on every request.

Calls

Methods mirror the API reference, and every example there has a TypeScript tab. The last argument of every method takes { idempotencyKey, signal }.

Resource	Methods
`emails`	send, batch, list, get, explain
`contacts`	upsert, list, get, update, delete
`lists`	list, create, get, update, delete, contacts, addContacts, removeContacts
`events`	record, list
`eventTypes`	list, get, create, update, delete
`templates`	list, get, create, update, upsert, delete, preview, addEssentials
`broadcasts`	draft, list, get, update, cancel, audiencePreview
`sequences`	create, list, get, update, on, off, simulate, enrollments, stepCounts
`webhooks`	create, list, get, delete, test, deliveries, resend
`domains`	add, list, get, verify, connect, remove
`account`	pauseMarketing
`(top level)`	me, health, getStarted, activity, testInbox, request

Anything else is one mailpark.request(method, path, { body, query }) away.

Errors

Any non-2xx response throws a MailparkError with status, code, message, fix and, for validation errors, fields. A network failure throws one with code network_error. See errors.

Webhooks

verifyWebhook(rawBody, signatureHeader, secret) checks the signature and returns the parsed event. See verifying webhooks.

CLI

Every command accepts --json for scripts and agents, and --api-url to point at another server.

Command	Does
`mailpark login --key sk_test_… --email you@acme.dev`	Save a key for this machine.
`mailpark init`	Set up templates and an emails/ folder in your project.
`mailpark templates push`	Publish every emails/<key>.html as a new version.
`mailpark test password-reset --to me`	Send a template to yourself.
`mailpark inbox`	Read the test inbox.
`mailpark logs --to jane@example.com`	Search the send log.
`mailpark explain msg_…`	Explain what happened to one email.
`mailpark sequences simulate seq_…`	Fast-forward a sequence.
`mailpark health`	Rates, trust level and usage.

Templates in your repo live in emails/<key>.html, with a header comment that templates push reads:

emails/trial-ending.html

<!--
key: trial-ending
type: marketing
subject: Your {{product_name}} trial ends in 3 days
-->
<html>…{{first_name}}…</html>