@mailjunky/sdk

Official Node.js SDK for MailJunky - AI-powered email automation.

Installation

npm install @mailjunky/sdk
# or
pnpm add @mailjunky/sdk
# or
yarn add @mailjunky/sdk

Quick Start

import { MailJunky } from '@mailjunky/sdk'

const client = new MailJunky({
  apiKey: 'mj_live_your_api_key'
})

// Send an email
await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Welcome!',
  html: '<h1>Welcome aboard!</h1>'
})

Features

• Send Emails - Transactional and marketing emails
• Track Events - User behavior tracking for automated workflows
• Manage Contacts - Store and segment your recipients
• TypeScript - Full type definitions included

API Reference

Emails

// Send a single email
await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Hello!',
  html: '<p>Hello World</p>',
  text: 'Hello World' // optional plain text fallback
})

// Send to multiple recipients
await client.emails.send({
  from: '[email protected]',
  to: ['[email protected]', '[email protected]'],
  cc: '[email protected]',
  bcc: ['[email protected]'],
  subject: 'Team Update',
  html: '<p>Important announcement...</p>'
})

Events

Track user events to trigger automated email workflows:

// Track a custom event
await client.events.track({
  event: 'product_viewed',
  user: '[email protected]',
  properties: {
    product_id: 'prod_123',
    price: 49.99
  }
})

// Track with session
await client.events.track({
  event: 'cart_added',
  user: '[email protected]',
  session_id: 'sess_abc123',
  properties: {
    product_id: 'prod_456',
    quantity: 2
  }
})

Contacts

Manage your recipient list:

// Create or update a contact
await client.contacts.upsert({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
  properties: {
    company: 'Acme Inc',
    plan: 'pro'
  },
  tags: ['customer', 'newsletter']
})

// Create a contact scoped to a specific domain
await client.contacts.upsert({
  email: '[email protected]',
  first_name: 'John',
  domain: 'yourapp.com', // Associates contact with this verified domain
  tags: ['customer']
})

// List contacts
const { data, pagination } = await client.contacts.list({
  page: 1,
  limit: 25,
  status: 'active',
  tag: 'customer'
})

// List contacts for a specific domain
const domainContacts = await client.contacts.list({
  domain: 'yourapp.com'
})

// Get a specific contact
const contact = await client.contacts.get('contact_id')

// Update a contact
await client.contacts.update('contact_id', {
  tags: ['customer', 'vip'],
  properties: { plan: 'enterprise' }
})

// Delete a contact
await client.contacts.delete('contact_id')

// Batch upsert contacts (all scoped to same domain)
await client.contacts.batch({
  domain: 'yourapp.com',
  contacts: [
    { email: '[email protected]', first_name: 'User', last_name: 'One' },
    { email: '[email protected]', first_name: 'User', last_name: 'Two' }
  ]
})

// Batch upsert with per-contact domain overrides
await client.contacts.batch({
  contacts: [
    { email: '[email protected]', domain: 'app1.com', first_name: 'User One' },
    { email: '[email protected]', domain: 'app2.com', first_name: 'User Two' }
  ]
})

Domain scoping: When your team has multiple verified domains, you can scope contacts to specific domains using the domain parameter. Pass the domain name (e.g. 'yourapp.com') — the server resolves it to the correct domain ID. Contacts without a domain are team-wide.

Error Handling

import { MailJunky, MailJunkyError } from '@mailjunky/sdk'

try {
  await client.emails.send({ /* ... */ })
} catch (error) {
  if (error instanceof Error && 'status' in error) {
    const apiError = error as MailJunkyError
    console.error(`API Error: ${apiError.message}`)
    console.error(`Status: ${apiError.status}`)
    console.error(`Code: ${apiError.code}`)
  }
}

Configuration

const client = new MailJunky({
  apiKey: 'mj_live_your_api_key',
  baseUrl: 'https://api.mailjunky.ai' // Optional, for self-hosted
})

License

MIT