@develemail/sdk

Node.js/TypeScript client SDK for the DevelEmail transactional email API. Zero runtime dependencies — uses the global fetch API (Node >= 18).

Quickstart

import { DevelEmail } from '@develemail/sdk';

const client = new DevelEmail({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-develemail-instance.com',
});

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

// Check delivery status
const email = await client.emails.get(id);
console.log(email.status); // 'queued' | 'delivered' | ...

Batch send

const result = await client.emails.batch([
  {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Hi',
    text: 'Hello A',
  },
  {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Hi',
    text: 'Hello B',
  },
]);

console.log(result.created); // 2
console.log(result.errors); // 0

Attachments

Pass a Buffer/Uint8Array for content and the SDK base64-encodes it for you — or pass an already-base64 string directly. Server caps: max 10 attachments per email, 5 MiB per file, 7 MiB combined decoded size.

import { readFile } from 'node:fs/promises';

const csv = await readFile('export.csv');

await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your export is ready',
  text: 'Attached: export.csv',
  attachments: [
    { filename: 'export.csv', content: csv, contentType: 'text/csv' },
  ],
});

Automatic retry + idempotency

Sends automatically retry on network errors, 5xx, and 429 responses with exponential backoff. Each send generates a unique Idempotency-Key header so retries never produce duplicate emails.

// Custom retry count (default: 3)
const client = new DevelEmail({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-instance.com',
  maxRetries: 5,
});

// Supply your own idempotency key
await client.emails.send(
  {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Hi',
    text: 'Hello',
  },
  { idempotencyKey: 'order-confirmation-12345' },
);

Error handling

import { DevelEmail, DevelEmailError } from '@develemail/sdk';

try {
  await client.emails.send({ ... });
} catch (err) {
  if (err instanceof DevelEmailError) {
    console.log(err.status);  // HTTP status code
    console.log(err.code);    // 'quota_exceeded', 'domain_not_verified', etc.
    console.log(err.message); // Human-readable message
  }
}

Domains & Templates

const domains = await client.domains.list();
const domain = await client.domains.get('domain-id');

const templates = await client.templates.list();
const template = await client.templates.get('template-id');

SMS

const { id, status } = await client.sms.send({
  to: '+15551234567',
  from: '+15557654321',
  body: 'Your order has shipped!',
});

// Or render an SMS template (created via the API) server-side
await client.sms.send({
  to: '+15551234567',
  templateName: 'otp-code',
  variables: { code: '482913' },
});

const message = await client.sms.get(id);
console.log(message.status); // 'queued' | 'delivered' | ...

const { data, nextCursor } = await client.sms.list({
  status: 'delivered',
  limit: 25,
});

Webhook verification

import { verifyWebhookSignature } from '@develemail/sdk';

const valid = await verifyWebhookSignature(
  rawBody,
  signatureHeader,
  webhookSecret,
);