posthawk

posthawk

Official Posthawk SDK for sending emails. TypeScript-first with React Email support.

Install

npm install posthawk

Quick Start

import { Posthawk } from 'posthawk';

const posthawk = new Posthawk('ck_live_...');

const { data, error } = await posthawk.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Welcome!',
  html: '<h1>Hello!</h1>',
});

if (error) {
  console.error(error.message);
} else {
  console.log('Sent!', data.jobId);
}

React Email

Use React Email components directly — no manual rendering needed.

npm install @react-email/render

import { Posthawk } from 'posthawk';
import { WelcomeEmail } from './emails/welcome';

const posthawk = new Posthawk('ck_live_...');

const { data, error } = await posthawk.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Welcome aboard!',
  react: WelcomeEmail({ name: 'Alex' }),
});

Schedule Emails

Send later by adding scheduledFor — accepts ISO 8601 strings or Date objects.

const { data, error } = await posthawk.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Reminder',
  text: "Don't forget your meeting tomorrow!",
  scheduledFor: '2026-03-15T09:00:00Z',
  timezone: 'America/New_York',
});

Check Delivery Status

const { data, error } = await posthawk.emails.get('job-id');

if (data) {
  console.log(data.status); // 'pending' | 'processing' | 'completed' | 'failed'
}

Manage Scheduled Emails

// List scheduled emails
const { data } = await posthawk.scheduled.list();

// Get a specific scheduled email
const { data } = await posthawk.scheduled.get('scheduled-id');

// Cancel a scheduled email
await posthawk.scheduled.cancel('scheduled-id');

// Reschedule to a new time
await posthawk.scheduled.reschedule('scheduled-id', {
  scheduledFor: new Date('2026-04-01T10:00:00Z'),
});

Self-Hosted

Point the SDK to your own Posthawk instance:

const posthawk = new Posthawk({
  apiKey: 'ck_live_...',
  baseUrl: 'https://api.yourdomain.com',
});

Error Handling

SDK methods never throw for API errors. Every method returns { data, error }:

const { data, error } = await posthawk.emails.send({ ... });

if (error) {
  console.error(error.message);    // Human-readable error message
  console.error(error.statusCode); // HTTP status code (e.g. 400, 429)
  return;
}

// data is guaranteed to be non-null here
console.log(data.jobId);

API Reference

posthawk.emails.send(params)

Send an email or schedule one for later delivery.

Parameter	Type	Required	Description
from	string	Yes	Sender email (must be from verified domain)
to	string | string[]	Yes	Recipient(s)
cc	string | string[]	No	CC recipient(s)
bcc	string | string[]	No	BCC recipient(s)
subject	string	Yes	Subject line
html	string	No*	HTML body
text	string	No*	Plain text body
react	ReactElement	No*	React Email component
templateId	string	No	Posthawk template ID
variables	Record<string, string>	No	Template variables
headers	Record<string, string>	No	Custom email headers
scheduledFor	string | Date	No	Schedule for later (ISO 8601 or Date)
timezone	string	No	IANA timezone
metadata	Record<string, unknown>	No	Custom metadata
tags	Record<string, unknown>	No	Custom tags

* At least one of html, text, react, or templateId is required.

posthawk.emails.get(jobId)

Get the delivery status of a queued email.

posthawk.scheduled.list(params?)

List scheduled emails. Optional filters: status, limit, offset.

posthawk.scheduled.get(id)

Get a specific scheduled email.

posthawk.scheduled.cancel(id)

Cancel a scheduled email before it sends.

posthawk.scheduled.reschedule(id, { scheduledFor })

Change the send time of a scheduled email.

License

MIT