❤
npm
Sign UpSign In

emailer-sdk
TypeScript icon, indicating that this package has built-in type declarations

1.0.1 • Public • Published

Emailer SDK for Node.js

The official Node.js SDK for Emailer - The modern email API for developers.

Features

  • 🚀 Simple, intuitive API
  • 📦 Lightweight with minimal dependencies
  • 🔄 Automatic retries with exponential backoff
  • 🎯 Full TypeScript support
  • 🔌 Support for all Emailer features (emails, templates, domains, webhooks, etc.)
  • ⚡ Promise-based async/await interface
  • ✅ NEW: Email validation before sending
  • 🚫 NEW: Suppression list management
  • 📊 NEW: Bounce statistics and analytics

Installation

npm install emailer-sdk
# or
yarn add emailer-sdk
# or
pnpm add emailer-sdk

Quick Start

import { Emailer } from 'emailer-sdk';
// or
const { Emailer } = require('emailer-sdk');

const emailer = new Emailer('your-api-key');

// Send your first email
const result = await emailer.emails.send({
  from: 'onboarding@yourdomain.com',
  to: 'user@gmail.com',
  subject: 'Hello World',
  html: '<strong>It works!</strong>',
  text: 'It works!'
});

console.log(result);
// { id: '5e858953-7b3f-4b47-a0f4-3c1e5d8ec041', ... }

Configuration

const emailer = new Emailer('your-api-key', {
  baseUrl: 'http://localhost:3000/api/v1', // Default for local development
  timeout: 30000, // 30 seconds
  retries: 3 // Number of retries for failed requests
});

Sending Emails

Basic Email

await emailer.emails.send({
  from: 'team@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<p>Welcome to our service!</p>',
  text: 'Welcome to our service!'
});

Multiple Recipients

await emailer.emails.send({
  from: 'team@yourdomain.com',
  to: [
    'user1@example.com',
    { email: 'user2@example.com', name: 'John Doe' }
  ],
  cc: 'manager@yourdomain.com',
  bcc: ['admin1@yourdomain.com', 'admin2@yourdomain.com'],
  subject: 'Team Update',
  html: '<p>Here is our weekly update...</p>'
});

With Attachments

import fs from 'fs';

await emailer.emails.sendWithAttachments({
  from: 'billing@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Your Invoice',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: fs.readFileSync('./invoice.pdf')
    },
    {
      filename: 'logo.png',
      content: fs.readFileSync('./logo.png'),
      disposition: 'inline',
      contentId: 'logo'
    }
  ]
});

Using Templates

await emailer.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  templateId: 'welcome-email',
  templateData: {
    name: 'John Doe',
    company: 'Acme Corp',
    activationUrl: 'https://app.yourdomain.com/activate'
  }
});

Scheduled Emails

await emailer.emails.send({
  from: 'reminders@yourdomain.com',
  to: 'user@example.com',
  subject: 'Reminder: Meeting Tomorrow',
  html: '<p>Don\'t forget about our meeting!</p>',
  scheduledAt: new Date('2024-12-25 09:00:00')
});

Batch Sending

const emails = [
  {
    from: 'newsletter@yourdomain.com',
    to: 'subscriber1@example.com',
    subject: 'Newsletter #1',
    html: '<p>Content...</p>'
  },
  {
    from: 'newsletter@yourdomain.com',
    to: 'subscriber2@example.com',
    subject: 'Newsletter #1',
    html: '<p>Content...</p>'
  }
];

const results = await emailer.emails.sendBatch(emails);

Email Tracking

// Enable tracking
await emailer.emails.send({
  from: 'marketing@yourdomain.com',
  to: 'lead@example.com',
  subject: 'Special Offer',
  html: '<p>Click <a href="https://example.com">here</a> for 50% off!</p>',
  trackOpens: true,
  trackClicks: true
});

// Get tracking events
const events = await emailer.emails.events('email-id');
console.log(events);
// [
//   { type: 'sent', timestamp: '2024-01-01T10:00:00Z' },
//   { type: 'delivered', timestamp: '2024-01-01T10:00:05Z' },
//   { type: 'opened', timestamp: '2024-01-01T10:30:00Z' },
//   { type: 'clicked', timestamp: '2024-01-01T10:31:00Z', data: { url: 'https://example.com' } }
// ]

Email Management

List Emails

const emails = await emailer.emails.list({
  page: 1,
  perPage: 50,
  status: 'sent',
  tag: 'marketing'
});

Get Email Details

const email = await emailer.emails.get('email-id');
console.log(email);
// {
//   id: 'email-id',
//   from: 'team@yourdomain.com',
//   to: ['user@example.com'],
//   subject: 'Hello',
//   status: 'delivered',
//   events: [...]
// }

Resend Email

const result = await emailer.emails.resend('email-id');

Cancel Scheduled Email

await emailer.emails.cancel('email-id');

Email Validation (Enhanced)

Validate Single Email

const validation = await emailer.emails.validate('user@example.com');
console.log(validation);
// {
//   valid: true,
//   syntax: true,
//   dns: true,
//   mx: true,
//   disposable: false,
//   role: false,
//   deliverable: true,
//   free: false,
//   score: 95,              // Deliverability score (0-100)
//   reason: null,           // Reason if invalid
//   suggestion: null        // Typo suggestion
// }

// Check before sending
if (validation.valid && validation.score > 50) {
  await emailer.emails.send({
    to: 'user@example.com',
    subject: 'Hello',
    html: '<p>Email validated!</p>'
  });
}

Suppression Management (NEW)

Check if Email is Suppressed

import { SuppressionType } from 'emailer-sdk';

const check = await emailer.suppression.check('bounced@example.com');
if (check.suppressed) {
  console.log(`Email suppressed: ${check.reason}`);
  // Don't send to this email
}

Add to Suppression List

// Add unsubscribed email
await emailer.suppression.add({
  email: 'unsubscribe@example.com',
  type: SuppressionType.UNSUBSCRIBE,
  reason: 'User clicked unsubscribe link'
});

// Add manual suppression
await emailer.suppression.add({
  email: 'donotcontact@example.com',
  type: SuppressionType.MANUAL,
  reason: 'Customer requested removal'
});

Get Bounce Statistics

const stats = await emailer.suppression.getBounceStats(30); // Last 30 days
console.log(stats);
// {
//   totalBounces: 150,
//   hardBounces: 100,
//   softBounces: 30,
//   complaints: 20,
//   bounceRate: 2.5,      // Percentage
//   period: '30 days'
// }

List Suppressed Emails

const list = await emailer.suppression.list({
  type: SuppressionType.BOUNCE,
  page: 1,
  limit: 50
});

console.log(`Total suppressed: ${list.pagination.total}`);
list.data.forEach(item => {
  console.log(`${item.email} - ${item.type}: ${item.reason}`);
});

Remove from Suppression List

await emailer.suppression.remove('reactivated@example.com');

Error Handling

try {
  await emailer.emails.send({
    from: 'team@yourdomain.com',
    to: 'invalid-email',
    subject: 'Test',
    html: '<p>Test</p>'
  });
} catch (error) {
  console.error('Error:', error.message);
  console.error('Status:', error.statusCode);
  console.error('Details:', error.details);
}

TypeScript Support

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

import { Emailer, EmailOptions, SendEmailResponse } from 'emailer-sdk';

const emailer = new Emailer('your-api-key');

const options: EmailOptions = {
  from: 'team@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hello World</p>'
};

const response: SendEmailResponse = await emailer.emails.send(options);

SDK Reference

emailer.emails

  • send(options) - Send a single email
  • sendBatch(emails) - Send multiple emails
  • sendWithAttachments(options) - Send email with attachments
  • get(id) - Get email details
  • list(params) - List emails
  • resend(id) - Resend an email
  • cancel(id) - Cancel a scheduled email
  • validate(email) - Validate email address
  • events(emailId) - Get email events

emailer.domains

  • create(domain) - Add a sending domain
  • get(id) - Get domain details
  • list() - List all domains
  • verify(id) - Verify domain records
  • delete(id) - Remove a domain

emailer.templates

  • create(template) - Create a template
  • get(id) - Get template details
  • list() - List all templates
  • update(id, template) - Update a template
  • delete(id) - Delete a template

emailer.webhooks

  • create(webhook) - Create a webhook
  • get(id) - Get webhook details
  • list() - List all webhooks
  • update(id, webhook) - Update a webhook
  • delete(id) - Delete a webhook
  • test(id) - Test webhook endpoint

emailer.contacts

  • create(contact) - Create a contact
  • get(id) - Get contact details
  • list(params) - List contacts
  • update(id, contact) - Update a contact
  • delete(id) - Delete a contact
  • unsubscribe(email) - Unsubscribe a contact

emailer.analytics

  • stats(query) - Get email statistics
  • events(query) - Get email events
  • domains(query) - Get domain statistics
  • tags(query) - Get tag statistics

Support

License

MIT

Readme

Keywords

Package Sidebar

Install

npm i emailer-sdk

Repository

github.com/MinhajSadik/Emailer

Homepage

github.com/MinhajSadik/Emailer/tree/main/_packages/emailer-sdk#readme

Weekly Downloads

136

Version

1.0.1

License

MIT

Unpacked Size

72.3 kB

Total Files

51

Last publish

Collaborators

  • minhajsadik
Try on RunKit
Report malware