SDK Reference

import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack('sk_live_...');

// Send an email
const { id } = await poststack.emails.send({
  from: 'PostStack <you@yourdomain.com>',
  to: ['user@example.com'],
  subject: 'Hello from PostStack',
  html: '<p>Welcome!</p>',
});

console.log('Email sent:', id);

import { PostStack, PostStackError } from '@poststack.dev/sdk';

const poststack = new PostStack('sk_live_...');

try {
  await poststack.emails.send({
    from: 'you@unverified-domain.com',
    to: ['user@example.com'],
    subject: 'Hello',
    html: '<p>Hi!</p>',
  });
} catch (error) {
  if (error instanceof PostStackError) {
    console.error(error.status);  // 422
    console.error(error.message); // "Domain not verified"
  }
}

// Send a single email with sender name
const { id } = await poststack.emails.send({
  from: 'PostStack <you@yourdomain.com>',
  to: ['user@example.com'],
  cc: ['teammate@example.com'],
  subject: 'Hello',
  html: '<p>Welcome!</p>',
  tags: ['welcome'],
  attachments: [
    { filename: 'doc.pdf', content: base64, content_type: 'application/pdf' },
  ],
});

// Send with a template
await poststack.emails.send({
  from: 'PostStack <you@yourdomain.com>',
  to: ['user@example.com'],
  template_id: 'tpl_abc123',
  variables: { first_name: 'Alice' },
});

// Batch send (up to 100)
const { data } = await poststack.emails.batch({
  emails: [
    { from: 'you@yourdomain.com', to: ['a@example.com'], subject: 'Hi A', html: '...' },
    { from: 'you@yourdomain.com', to: ['b@example.com'], subject: 'Hi B', html: '...' },
  ],
});

// List emails with filters
const { data: emails, meta } = await poststack.emails.list({
  status: 'delivered',
  tag: 'welcome',
  date_from: '2026-03-01',
});

// Get email details, events, and insights
const email = await poststack.emails.get('em_abc123');
const { events } = await poststack.emails.getEvents('em_abc123');
const { warnings } = await poststack.emails.getInsights('em_abc123');

// Reschedule or cancel
await poststack.emails.reschedule('em_abc123', '2026-03-26T14:00:00Z');
await poststack.emails.cancel('em_abc123');

// Add a domain with region and TLS
const domain = await poststack.domains.create({
  name: 'yourdomain.com',
  region: 'eu-west-1',
  tls_mode: 'enforced',
});

// Verify, update, assign IP
await poststack.domains.verify(domain.id);
await poststack.domains.update(domain.id, {
  open_tracking: true,
  catch_all: true,
});
await poststack.domains.assignIp(domain.id, 1);

// DMARC reporting
const stats = await poststack.domains.getDmarcStats(domain.id, 30);
const { data: reports } = await poststack.domains.getDmarcReports(domain.id);
const { sources } = await poststack.domains.getDmarcSources(domain.id);

// Create a contact with custom properties
const contact = await poststack.contacts.create({
  email: 'alice@example.com',
  first_name: 'Alice',
  properties: { plan: 'pro', company: 'Acme' },
});

// List, search, update
const { data: contacts } = await poststack.contacts.list({ search: 'alice' });
await poststack.contacts.update('ct_abc123', { properties: { plan: 'enterprise' } });

// Import contacts (up to 10,000)
const result = await poststack.contacts.import({
  contacts: [
    { email: 'bob@example.com', first_name: 'Bob', properties: { plan: 'free' } },
  ],
});

// Export, unsubscribe, delete
const csv = await poststack.contacts.exportCsv();
await poststack.contacts.unsubscribe('ct_abc123');
await poststack.contacts.delete('ct_abc123');

// Create with A/B testing
const { broadcast } = await poststack.broadcasts.create({
  name: 'Newsletter',
  from: 'Newsletter <news@yourdomain.com>',
  subject: 'March Updates',
  html: '<p>Content...</p>',
  segment_id: 'seg_abc123',
  ab_test: {
    variants: [
      { name: 'A', subject: 'March Updates', weight: 50 },
      { name: 'B', subject: 'What is new in March', weight: 50 },
    ],
    test_sample_size: 20,
    test_duration_minutes: 120,
  },
});

// Test, send, get variant stats
await poststack.broadcasts.sendTest(broadcast.id, { email: 'test@yourdomain.com' });
await poststack.broadcasts.send(broadcast.id);
const stats = await poststack.broadcasts.getVariantStats(broadcast.id);

// Create and build a workflow
const { workflow } = await poststack.workflows.create({
  name: 'Onboarding',
  trigger_type: 'contact.created',
});

// Add steps
await poststack.workflows.addStep(workflow.id, {
  step_type: 'send_email',
  config: { template_id: 'tpl_welcome' },
  position: 0,
});
await poststack.workflows.addStep(workflow.id, {
  step_type: 'wait',
  config: { delay: '2d' },
  position: 1,
});

// Activate, pause, trigger manually
await poststack.workflows.activate(workflow.id);
await poststack.workflows.pause(workflow.id);
await poststack.workflows.trigger(workflow.id, { contact_id: 1 });

// Create, update, test
const webhook = await poststack.webhooks.create({
  url: 'https://yourdomain.com/webhooks',
  events: ['email.delivered', 'email.bounced'],
});
await poststack.webhooks.update(webhook.id, { enabled: true });
await poststack.webhooks.test(webhook.id);

// View delivery history, replay failed
const { data: deliveries } = await poststack.webhooks.getDeliveries(webhook.id);
await poststack.webhooks.replay(webhook.id, deliveryId);

// Contact Properties
const { properties } = await poststack.contactProperties.list();
await poststack.contactProperties.create({
  name: 'plan', label: 'Plan', type: 'select', options: ['free', 'pro'],
});

// Suppressions
await poststack.suppressions.add({ email: 'bad@example.com', reason: 'manual' });
await poststack.suppressions.remove('bad@example.com');

// Email Validations
const result = await poststack.emailValidations.validate('test@example.com');
const { results } = await poststack.emailValidations.validateBatch([
  'a@example.com', 'b@example.com',
]);

// Signup Forms
const form = await poststack.signupForms.create({
  name: 'Newsletter', segment_id: 1,
  fields: [{ name: 'email', type: 'email', label: 'Email', required: true }],
});
await poststack.signupForms.submit(form.id, { email: 'new@example.com' });

// Subscription Topics
const { topics } = await poststack.subscriptionTopics.list();
await poststack.subscriptionTopics.subscribe(contactId, topicId);

// Inbound Emails
const { data: inbound } = await poststack.inboundEmails.list();
await poststack.inboundEmails.reply(inboundId, {
  from: 'Support <support@yourdomain.com>',
  html: '<p>Thanks for reaching out!</p>',
});

import type {
  SendEmailInput,
  Email,
  EmailEvent,
  Contact,
  Domain,
  DmarcStats,
  Template,
  Webhook,
  WebhookDelivery,
  Broadcast,
  BroadcastVariant,
  Segment,
  Workflow,
  WorkflowStep,
  Mailbox,
  Suppression,
  EmailValidation,
  ContactProperty,
  SignupForm,
  SubscriptionTopic,
  PaginatedResponse,
} from '@poststack.dev/sdk';