solen-sdk

solen-sdk

Official Node.js / TypeScript SDK for Solen, the email platform.

Send transactional emails with a template identifier, a recipient, and variables — nothing else. Solen handles template rendering, provider communication, and logging for you.

Installation

npm install solen-sdk

Requires Node.js 18 or newer (uses the built-in fetch). Zero runtime dependencies.

Quick start

import EmailClient from "solen-sdk";

const client = new EmailClient({
  apiKey: process.env.SOLEN_API_KEY!, // solen_xxxxxxxx_...
});

const result = await client.send({
  template: "welcome-email",
  to: "user@example.com",
  variables: { name: "Ada", plan: "Pro" },
});

console.log(result.id); // platform log id — look it up in the dashboard's Logs section

Get your API key from the Solen dashboard under your project's settings. Templates and their {{variables}} are defined in the dashboard as well.

Configuration

const client = new EmailClient({
  apiKey: "solen_xxxxxxxx_...",             // required
  baseUrl: "https://solenapi.biswajitrath.com", // optional, this is the default
  timeoutMs: 15000,                          // optional, default 15000
});

Option	Type	Default	Description
apiKey	string	—	Project API key from the Solen dashboard.
baseUrl	string	https://solenapi.biswajitrath.com	Solen API endpoint. Override for self-hosted or local development (e.g. http://localhost:4000).
timeoutMs	number	15000	Request timeout in milliseconds.

API

client.send(input)

Sends a transactional email. Returns a Promise<SendEmailResult>.

interface SendEmailInput {
  template: string;                                        // template slug, e.g. "welcome-email"
  to: string;                                              // recipient email address
  variables?: Record<string, string | number | boolean>;   // values for {{variables}}
}

interface SendEmailResult {
  id: string;                    // platform log id for this send
  status: "SUCCESS" | "FAILED";
  messageId?: string;            // provider message id, when available
}

Error handling

All failures throw an EmailError with a machine-readable code:

import EmailClient, { EmailError } from "solen-sdk";

try {
  await client.send({ template: "welcome-email", to: "user@example.com" });
} catch (err) {
  if (err instanceof EmailError) {
    console.error(err.code);    // e.g. "INVALID_PAYLOAD", "TIMEOUT", "NETWORK_ERROR"
    console.error(err.status);  // HTTP status (0 for client-side errors)
    console.error(err.logId);   // platform log id, when the request was logged before failing
  }
  throw err;
}

Code	Meaning
MISSING_API_KEY	No apiKey was provided to the client.
INVALID_PAYLOAD	template missing or to is not a valid email address.
TIMEOUT	The request exceeded timeoutMs.
NETWORK_ERROR	The Solen API could not be reached.
HTTP_* / other	Error code returned by the Solen API (see the dashboard logs).

TypeScript

The package ships its own type declarations — no @types package needed. All public types (EmailClientOptions, SendEmailInput, SendEmailResult, EmailError) are exported.

License

MIT Biswajit Rath