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: '[email protected]',
  to: '[email protected]',
  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: '[email protected]',
  to: '[email protected]',
  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: '[email protected]',
  to: '[email protected]',
  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