@cdv2/email

TypeScript SDK for the cd2 email API. Works in Node.js and the browser (uses native fetch).

Installation

npm install @cdv2/email

Setup

import { EmailClient } from "@cdv2/email";

const client = new EmailClient({
  apiKey: "your-api-key",
  baseUrl: "https://mail.yourdomain.com",
});

Usage

Send an email

const { data, error } = await client.send({
  from: "Sender Name <[email protected]>", // display name optional
  to: "[email protected]", // or an array
  subject: "Hello",
  html: "<p>Hello world</p>",
  text: "Hello world",
});

if (error) {
  console.error(error.message);
} else {
  console.log("Sent:", data.id);
}

Retrieve a sent email

const { data, error } = await client.get("email-id");

if (data) {
  console.log(data.status); // "sent" | "delivered" | "bounced" | ...
}

API

new EmailClient(opts)

| Option | Type | Description | | --------- | -------- | -------------------------------------------- | | apiKey | string | Your cd2 API key | | baseUrl | string | Base URL of your cd2 sender API instance |

client.send(params)

| Param | Type | Required | Description | | --------- | ---------------------- | -------- | ---------------------------------- | | from | string | Yes | Verified sender address. Supports RFC 5322 display names: "Name <[email protected]>" | | to | string \| string[] | Yes | One or more recipient addresses | | subject | string | Yes | | | html | string | No | HTML body | | text | string | No | Plain-text body | | cc | string \| string[] | No | Carbon copy recipients | | bcc | string \| string[] | No | Blind carbon copy recipients | | replyTo | string | No | Reply-to address | | headers | Record<string,string>| No | Custom email headers (e.g. List-Unsubscribe) forwarded to SES |

Returns Promise<EmailSdkResult<{ id: string }>>.

client.get(id)

Retrieves a sent email by its record ID. Returns Promise<EmailSdkResult<GetEmailResult>>.

GetEmailResult

| Field | Type | Description | | ----------- | ---------------------- | ---------------------------------------- | | id | string | Record ID | | from | string | Sender address | | to | string[] | Recipient addresses | | subject | string | | | html | string \| null | HTML body | | text | string \| null | Plain-text body | | cc | string[] \| null | | | bcc | string[] \| null | | | replyTo | string[] \| null | | | headers | Record<string,string> \| null | Custom headers as sent | | status | EmailStatus | See below | | createdAt | string | ISO 8601 | | updatedAt | string | ISO 8601 |

EmailStatus

"queued" | "sending" | "sent" | "delivered" | "delivery_delayed" | "bounced" | "complained" | "failed" | "scheduled" | "canceled"

EmailSdkResult<T>

All methods return a discriminated union — never throws:

| { data: T; error: null }
| { data: null; error: { message: string } }