Keplars Email SDK for JavaScript/TypeScript

Official JavaScript/TypeScript SDK for the Keplars Email API - modern transactional email service with priority-based delivery.

Installation

npm install keplars
# or
yarn add keplars
# or
bun add keplars

Quick Start

import { Keplars } from 'keplars';

const client = new Keplars({
  apiKey: 'kms_<workspaceId>.live_<secret>'
});

const response = await client.emails.sendInstant({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your verification code is 123456',
  html: '<p>Your verification code is <strong>123456</strong></p>'
});

console.log('Job ID:', response.data.job_id);

Configuration

const client = new Keplars({
  apiKey: 'your-api-key',
  baseUrl: 'https://custom.api',
  timeout: 30000,
  maxRetries: 3,
  retryDelay: 1000
});

Environment Variables

• KEPLARS_API_KEY - Your API key
• KEPLARS_BASE_URL - Custom API base URL

API Key Types

| Type | Format | Used for | |---|---|---| | Regular | kms_<id>.live_<secret> | Email sending | | Admin | kms_<id>.adm_<secret> | Contacts, audiences, automations, domains |

Email Sending

Priority Levels

| Method | Delivery | Use case | |---|---|---| | sendInstant | 0–5 sec | OTPs, login codes, critical alerts | | sendHigh | 0–30 sec | Transactional, notifications | | sendAsync / send | 0–5 min | General transactional | | sendBulk | Idle | Newsletters, marketing |

const response = await client.emails.sendInstant({
  from: '[email protected]',
  to: [{ email: '[email protected]', name: 'John Doe' }],
  subject: 'Welcome!',
  html: '<h1>Welcome aboard</h1>'
});

console.log(response.data.job_id);
console.log(response.data.priority);

Request Fields

| Field | Type | Required | Description | |---|---|---|---| | to | string \| EmailRecipient[] | Yes | Recipient(s) | | from | string | Yes | Sender email | | subject | string | Yes | Email subject | | html | string | One of | HTML body | | text | string | One of | Plain text body | | template_id | string | One of | Template ID | | template_data | object | No | Template variables | | cc | EmailRecipient[] | No | CC recipients | | bcc | EmailRecipient[] | No | BCC recipients | | reply_to | string | No | Reply-to address | | custom_headers | object | No | Custom email headers |

Response Shape

{
  success: true,
  message: 'Email queued',
  data: {
    job_id: 'job_abc123',
    priority: 'instant'
  }
}

Send with Template

const response = await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Password Reset',
  template_id: 'tpl_reset_password',
  template_data: {
    name: 'John',
    reset_link: 'https://example.com/reset/token123'
  }
});

Schedule Email

const response = await client.emails.schedule({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your weekly digest',
  html: '<p>Here is your weekly digest...</p>',
  scheduled_for: '2026-06-01T09:00:00Z',
  priority: 'bulk'
});

Contacts (Admin API Key Required)

const adminClient = new Keplars({
  apiKey: 'kms_<workspaceId>.adm_<secret>'
});

await adminClient.contacts.add({
  email: '[email protected]',
  name: 'John Doe',
  audience_id: 'aud_abc123'
});

const contact = await adminClient.contacts.get('[email protected]');

const contacts = await adminClient.contacts.list('aud_abc123', 1, 20);

await adminClient.contacts.update('[email protected]', { name: 'Jane Doe' });

await adminClient.contacts.delete('[email protected]');

Audiences (Admin API Key Required)

const audience = await adminClient.audiences.create('Newsletter Subscribers', 'Main newsletter list');

const audiences = await adminClient.audiences.list(1, 20);

const audience = await adminClient.audiences.get('aud_abc123');

await adminClient.audiences.delete('aud_abc123');

Automations (Admin API Key Required)

const automations = await adminClient.automations.list();

const automation = await adminClient.automations.get('auto_abc123');

await adminClient.automations.enroll('auto_abc123', '[email protected]');

await adminClient.automations.unenroll('auto_abc123', '[email protected]');

Domains (Admin API Key Required)

const domain = await adminClient.domains.add('mail.yourcompany.com');

const domains = await adminClient.domains.list();

const status = await adminClient.domains.getStatus('dom_abc123');

const result = await adminClient.domains.verify('dom_abc123');

const apiKey = await adminClient.domains.createApiKey({ domain_id: 'dom_abc123', name: 'Production Key' });

await adminClient.domains.delete('dom_abc123');

Error Handling

import { Keplars, AuthenticationError, RateLimitError } from 'keplars';

try {
  const response = await client.emails.sendInstant({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, retry after:', error.retryAfter);
  }
}

TypeScript Types

import type {
  EmailRecipient,
  SendEmailRequest,
  SendEmailResponse,
  Contact,
  Audience,
  Automation,
} from 'keplars';