qqueue-sdk

TypeScript SDK for the self-hosted QQueue email API.

License

The QQueue SDK is licensed under the MIT License. See LICENSE.

Install

npm install qqueue-sdk

Usage

import { QQueueClient } from "qqueue-sdk";

const qqueue = new QQueueClient({
  apiKey: process.env.QQUEUE_API_KEY!,
  baseUrl: "https://mail.example.com/api/v1"
});

const email = await qqueue.sendEmail({
  to: "[email protected]",
  subject: "Welcome",
  html: "<p>Hello from QQueue.</p>",
  text: "Hello from QQueue."
});

console.log(email.id, email.status);

Templates

await qqueue.sendEmail({
  to: "[email protected]",
  templateId: "tpl_123",
  variables: {
    firstName: "Ada",
    resetUrl: "https://app.example.com/reset/token"
  }
});

The API key determines the QQueue organization, so SDK calls do not include an organizationId.

Choosing who it sends as

The From header comes from a sending account configured in QQueue, so you never set it on the request. Name the account by the address it sends as:

await qqueue.sendEmail({
  from: "[email protected]",
  to: "[email protected]",
  replyTo: "[email protected]",
  subject: "Welcome",
  text: "Hello."
});

Omit from and the organization's default sending account is used. Pass smtpConnectionId instead to name an account by id (it wins if you send both). An address no sending account uses is a 404, not a fall back to the default.

replyTo is optional twice over: leave it out and the send inherits whatever default Reply-To the sending account has, if any.

Errors

import { QQueueClient, QQueueError } from "qqueue-sdk";

try {
  await qqueue.sendEmail({
    to: "[email protected]",
    subject: "Welcome",
    text: "Hello"
  });
} catch (error) {
  if (error instanceof QQueueError) {
    console.error(error.status, error.code, error.message);
  }
}

Self-Hosting

Point baseUrl at your QQueue API URL. For example, if QQueue is hosted at https://mail.example.com, use:

const qqueue = new QQueueClient({
  apiKey: process.env.QQUEUE_API_KEY!,
  baseUrl: "https://mail.example.com/api/v1"
});

Releases

See CHANGELOG.md for version history and RELEASE.md for the publishing checklist, install smoke test, and version bump flow.