TypeScript SDK

npm install @pigeons/pigeons-ts

import { Pigeons } from '@pigeons/pigeons-ts'

const pigeons = new Pigeons({
  baseUrl: 'https://pigeons.yourdomain.com',
  apiKey: 'pgn_your_key_here',
})

const email = await pigeons.emails.send({
  to: 'alice@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome aboard</h1>',
})

console.log(email.id)     // msg_abc123...
console.log(email.status) // "queued"

const email = await pigeons.emails.send({
  to: 'alice@example.com',
  templateId: 'welcome-email', // slug or tpl_ ID
  data: { name: 'Alice', company: 'Acme' },
})

const email = await pigeons.emails.send({
  to: ['alice@example.com', 'bob@example.com'],
  cc: ['manager@example.com'],
  subject: 'Team Update',
  html: '<p>Here is your update.</p>',
})

const email = await pigeons.emails.send({
  to: 'alice@example.com',
  subject: 'Reminder',
  text: 'Your trial expires tomorrow.',
  scheduledAt: '2024-06-01T09:00:00Z',
})

const email = await pigeons.emails.get('msg_abc123...')
console.log(email.status) // "delivered"

const page = await pigeons.emails.list({ limit: 10, status: 'delivered' })

for (const email of page.data) {
  console.log(email.id, email.subject, email.status)
}

if (page.has_more) {
  const next = await pigeons.emails.list({ cursor: page.next_cursor! })
}

const cancelled = await pigeons.emails.cancel('msg_abc123...')

const results = await pigeons.emails.batch([
  { to: 'alice@example.com', subject: 'Hi Alice', text: 'Hello!' },
  { to: 'bob@example.com', subject: 'Hi Bob', text: 'Hello!' },
])

const email = await pigeons.emails.send(
  { to: 'alice@example.com', subject: 'Order #123', html: '...' },
  { idempotencyKey: 'order-123-confirmation' },
)

const contact = await pigeons.contacts.create({
  email: 'alice@example.com',
  firstName: 'Alice',
  lastName: 'Smith',
  tags: ['newsletter', 'beta'],
  properties: { plan: 'pro', signupSource: 'website' },
})

// By ID
const contact = await pigeons.contacts.get('ctc_abc123...')

// By email
const contact = await pigeons.contacts.get('alice@example.com')

const updated = await pigeons.contacts.update('ctc_abc123...', {
  tags: ['newsletter', 'beta', 'vip'],
  properties: { plan: 'enterprise' },
})

const page = await pigeons.contacts.list({ tag: 'newsletter', limit: 50 })

await pigeons.contacts.delete('ctc_abc123...')

const result = await pigeons.contacts.batchCreate([
  { email: 'alice@example.com', firstName: 'Alice', tags: ['import'] },
  { email: 'bob@example.com', firstName: 'Bob', tags: ['import'] },
])
console.log(result.created) // 2
console.log(result.skipped) // 0

// Global unsubscribe
await pigeons.contacts.unsubscribe('ctc_abc123...')

// Per-topic unsubscribe
await pigeons.contacts.unsubscribe('ctc_abc123...', { topicId: 'top_xyz...' })

// Resubscribe
await pigeons.contacts.resubscribe('ctc_abc123...')

const template = await pigeons.templates.create({
  slug: 'welcome-email',
  name: 'Welcome Email',
  subject: 'Welcome, {{name}}!',
  body: '<h1>Welcome to {{company}}</h1><p>Hi {{name}},</p>',
  sampleData: { name: 'Alice', company: 'Acme' },
})

const tpl = await pigeons.templates.get('welcome-email') // by slug or ID
const updated = await pigeons.templates.update('welcome-email', { subject: 'New subject' })
await pigeons.templates.delete('welcome-email')

const preview = await pigeons.templates.preview('welcome-email', {
  name: 'Alice',
  company: 'Acme',
})
console.log(preview.subject) // "Welcome, Alice!"
console.log(preview.html)    // rendered HTML

const campaign = await pigeons.campaigns.create({
  name: 'Product Launch',
  templateId: 'product-launch',
  templateData: { launchDate: '2024-06-01' },
  audienceFilter: { tags: { contains: 'newsletter' } },
})

// Send immediately
await pigeons.campaigns.send(campaign.id)

// Or schedule
await pigeons.campaigns.send(campaign.id, {
  scheduledAt: '2024-06-01T09:00:00Z',
})

await pigeons.campaigns.pause(campaign.id)
await pigeons.campaigns.resume(campaign.id)
await pigeons.campaigns.cancel(campaign.id)

const campaign = await pigeons.campaigns.get('cmp_abc123...')
console.log(campaign.stats)
// { total: 500, sent: 450, delivered: 440, opened: 120, bounced: 5, complained: 1, failed: 4 }

const sequence = await pigeons.sequences.create({
  name: 'Onboarding',
  steps: [
    { type: 'email', templateId: 'welcome-email', subject: 'Welcome!' },
    { type: 'delay', delayDuration: '1d' },
    { type: 'email', templateId: 'getting-started', subject: 'Getting Started' },
    { type: 'delay', delayDuration: '3d' },
    { type: 'email', templateId: 'tips', subject: 'Pro Tips' },
  ],
})

await pigeons.sequences.activate(sequence.id)

const enrollment = await pigeons.sequences.enroll(sequence.id, 'ctc_abc123...')
console.log(enrollment.status) // "active"

const page = await pigeons.sequences.enrollments(sequence.id, { status: 'active' })

const inbox = await pigeons.inboxes.create({
  name: 'Support',
  emailAddress: 'support@yourdomain.com',
  webhookUrl: 'https://your-app.com/webhooks/email',
})

await pigeons.inboxes.pause(inbox.id)
await pigeons.inboxes.resume(inbox.id)
await pigeons.inboxes.setCatchAll(inbox.id)
await pigeons.inboxes.delete(inbox.id)

const messages = await pigeons.inboxes.messages.list(inbox.id, {
  direction: 'inbound',
  limit: 10,
})

const message = await pigeons.inboxes.messages.get(inbox.id, 'imsg_abc123...')

const sent = await pigeons.inboxes.messages.create(inbox.id, {
  to: 'customer@example.com',
  subject: 'Re: Your ticket',
  html: '<p>Thanks for reaching out.</p>',
  inReplyTo: 'imsg_previous...', // maintains thread
})

const threads = await pigeons.inboxes.threads.list(inbox.id, { status: 'open' })

const thread = await pigeons.inboxes.threads.get(inbox.id, 'thr_abc123...')

await pigeons.inboxes.threads.update(inbox.id, 'thr_abc123...', {
  status: 'closed',
})

const webhook = await pigeons.webhooks.create({
  url: 'https://your-app.com/webhooks/pigeons',
  events: ['email.delivered', 'email.bounced', 'inbox.message.received'],
})

// The secret is only returned on creation
console.log(webhook.secret) // "whsec_..."

const domain = await pigeons.domains.add({ domain: 'example.com' })
console.log(domain.records) // DNS records to add

// Re-check verification
const verified = await pigeons.domains.verify(domain.id)
console.log(verified.verificationStatus) // "verified"

import { PigeonsError, NotFoundError, AuthError, RateLimitError } from '@pigeons/pigeons-ts'

try {
  await pigeons.emails.get('msg_nonexistent')
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log(err.message)    // "Email 'msg_nonexistent' not found"
    console.log(err.statusCode) // 404
    console.log(err.code)       // "not_found"
    console.log(err.type)       // "not_found"
  }
}