@emailr/sdk

Official Emailr API SDK for TypeScript/JavaScript.

Installation

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

Quick Start

import { Emailr } from '@emailr/sdk';

const emailr = new Emailr({ apiKey: 'your-api-key' });

// Send an email
const result = await emailr.emails.send({
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Hello!',
  html: '<h1>Hello World</h1>',
});

console.log(result.message_id);

Configuration

const emailr = new Emailr({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.emailr.dev', // optional
  timeout: 30000, // optional, in milliseconds
});

Resources

Emails

// Send an email
const result = await emailr.emails.send({
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Hello!',
  html: '<h1>Hello World</h1>',
  text: 'Hello World',
});

// Send with a template
const result = await emailr.emails.send({
  to: '[email protected]',
  template_id: 'template-uuid',
  template_data: { name: 'John', company: 'Acme' },
});

// Get email by ID
const email = await emailr.emails.get('email-uuid');

// List emails
const emails = await emailr.emails.list({ page: 1, limit: 50 });

Contacts

// Create a contact
const contact = await emailr.contacts.create({
  email: '[email protected]',
  first_name: 'John',
  last_name: 'Doe',
  metadata: { source: 'website' },
});

// List contacts
const contacts = await emailr.contacts.list({ limit: 100 });

// Update a contact
const updated = await emailr.contacts.update('contact-uuid', {
  first_name: 'Jane',
});

// Delete a contact
await emailr.contacts.delete('contact-uuid');

// Bulk create contacts
const result = await emailr.contacts.bulkCreate({
  contacts: [
    { email: '[email protected]', first_name: 'User 1' },
    { email: '[email protected]', first_name: 'User 2' },
  ],
});

Templates

// Create a template
const template = await emailr.templates.create({
  name: 'Welcome Email',
  subject: 'Welcome to {{company}}',
  html_content: '<h1>Welcome {{name}}</h1>',
  variables: ['name', 'company'],
});

// List templates
const templates = await emailr.templates.list();

// Update a template
const updated = await emailr.templates.update('template-uuid', {
  subject: 'New Subject',
});

// Delete a template
await emailr.templates.delete('template-uuid');

Domains

// Add a domain
const domain = await emailr.domains.add({ domain: 'example.com' });

// List domains
const domains = await emailr.domains.list();

// Verify domain
const status = await emailr.domains.verify('domain-uuid');

// Check DNS status
const dnsStatus = await emailr.domains.checkDns('domain-uuid');

// Delete a domain
await emailr.domains.delete('domain-uuid');

Webhooks

// Create a webhook
const webhook = await emailr.webhooks.create({
  name: 'Email Events',
  url: 'https://api.example.com/webhooks',
  events: ['email.sent', 'email.delivered', 'email.bounced'],
});

// List webhooks
const webhooks = await emailr.webhooks.list();

// Enable/disable webhook
await emailr.webhooks.enable('webhook-uuid');
await emailr.webhooks.disable('webhook-uuid');

// Delete a webhook
await emailr.webhooks.delete('webhook-uuid');

Broadcasts

// Create a broadcast
const broadcast = await emailr.broadcasts.create({
  name: 'Newsletter - January',
  subject: 'Your monthly update',
  from_email: '[email protected]',
  segment_id: 'segment-uuid',
  html_content: '<h1>Newsletter</h1>',
});

// Send a broadcast
const result = await emailr.broadcasts.send('broadcast-uuid');

// Schedule a broadcast
await emailr.broadcasts.schedule('broadcast-uuid', '2024-01-15T10:00:00Z');

// Cancel a scheduled broadcast
await emailr.broadcasts.cancel('broadcast-uuid');

Segments

// Create a segment
const segment = await emailr.segments.create({
  name: 'Active Users',
  description: 'Users who opened an email in the last 30 days',
  conditions: { opened_email: { within_days: 30 } },
});

// List segments
const segments = await emailr.segments.list();

// Get contacts in a segment
const contacts = await emailr.segments.getContacts('segment-uuid');

// Get segment count
const count = await emailr.segments.getCount('segment-uuid');

Error Handling

import { Emailr, EmailrError, ValidationError, RateLimitError } from '@emailr/sdk';

try {
  await emailr.emails.send({ to: 'invalid-email' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message, error.details);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter, 'seconds');
  } else if (error instanceof EmailrError) {
    console.error('API error:', error.message, error.statusCode, error.code);
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions for all API requests and responses.

import type { SendEmailRequest, Email, Contact } from '@emailr/sdk';

const request: SendEmailRequest = {
  to: '[email protected]',
  subject: 'Hello',
  html: '<h1>Hello</h1>',
};

License

MIT