@pulsesend/javascript

Official JavaScript/TypeScript SDK for the PulseSend API.

Installation

npm install @pulsesend/javascript
# or
yarn add @pulsesend/javascript
# or
bun add @pulsesend/javascript

Quick Start

import { PulseSend } from '@pulsesend/javascript'

const client = new PulseSend('pk_live_your_api_key_here')

// Send an email
await client.emails.send({
  to: ['[email protected]'],
  from: '[email protected]',
  subject: 'Welcome {{name}}!',
  html: '<h1>Hello {{name}}!</h1><p>Welcome to our platform.</p>',
  variables: {
    name: 'John Doe'
  }
})

Configuration

Basic Configuration

const client = new PulseSend('pk_live_your_api_key_here')

Advanced Configuration

const client = new PulseSend({
  apiKey: 'pk_live_your_api_key_here',
  baseUrl: 'https://api.pulsesend.com/v1', // Optional
  timeout: 10000, // Optional, default: 10s
  retries: 3, // Optional, default: 3
  retryDelay: 1000 // Optional, default: 1s
})

API Reference

Emails

Send Email

const result = await client.emails.send({
  to: ['[email protected]'],
  from: '[email protected]',
  subject: 'Your Subject',
  html: '<p>Your HTML content</p>',
  // Optional fields
  text: 'Your plain text content',
  cc: ['[email protected]'],
  bcc: ['[email protected]'],
  variables: { name: 'John' },
  tags: ['marketing'],
  metadata: { campaign: 'welcome' },
  sendAt: new Date('2024-01-01T10:00:00Z')
})

List Emails

const emails = await client.emails.list({
  status: 'delivered',
  limit: 50,
  offset: 0,
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31')
})

Get Email

const email = await client.emails.get('email_id')

Cancel Email

await client.emails.cancel('email_id')

Analytics

Overview

const analytics = await client.analytics.overview({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  tags: ['marketing']
})

Engagement

const engagement = await client.analytics.engagement()

Reputation

const reputation = await client.analytics.reputation()

Error Handling

The SDK provides specific error classes for different scenarios:

import { 
  InvalidApiKeyError,
  QuotaExceededError,
  RateLimitError,
  ValidationError,
  NetworkError,
  TimeoutError,
  ServerError
} from '@pulsesend/javascript'

try {
  await client.emails.send(emailData)
} catch (error) {
  if (error instanceof QuotaExceededError) {
    console.log('Quota exceeded, upgrade your plan')
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${error.retryAfter} seconds`)
  } else if (error instanceof ValidationError) {
    console.log('Validation error:', error.details)
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import { SendEmailRequest, SendEmailResponse } from '@pulsesend/javascript'

const request: SendEmailRequest = {
  to: ['[email protected]'],
  from: '[email protected]',
  subject: 'Test',
  html: '<p>Test</p>'
}

const response: SendEmailResponse = await client.emails.send(request)

Retry Logic

The SDK automatically retries failed requests with exponential backoff for:

• Network errors
• Timeout errors
• Server errors (5xx)
• Rate limiting (with proper delay)

Environment Variables

You can set your API key using environment variables:

export PULSESEND_API_KEY=pk_live_your_api_key_here

const client = new PulseSend(process.env.PULSESEND_API_KEY!)

Examples

See the examples directory for more usage examples.

License

MIT © PulseSend