Autopilot Mails TypeScript SDK

Send transactional email from a Node.js application through Autopilot Mails. The SDK intentionally exposes sending only; inbox access belongs to the MCP integration.

Install

npm install @autopilotstartup/mail

Node.js 18 or newer is required.

Send an email

Create an application API key with the emails:send scope, then:

import { AutopilotMail } from "@autopilotstartup/mail";

const mail = new AutopilotMail({
  apiKey: process.env.AUTOPILOT_MAILS_API_KEY!,
});

const email = await mail.emails.send({
  from: "[email protected]",
  to: "[email protected]",
  subject: "Your report is ready",
  text: "The report has been generated.",
});

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

Addresses can be strings or objects with a display name:

await mail.emails.send({
  from: { email: "[email protected]", name: "Report Agent" },
  to: ["[email protected]", { email: "[email protected]", name: "Second" }],
  replyTo: "[email protected]",
  subject: "Your report is ready",
  html: "<p>The report has been generated.</p>",
});

The SDK generates an idempotency key for every send. Supply your own when a job may be retried so every attempt resolves to the same queued email:

await mail.emails.send(message, { idempotencyKey: `report-${reportId}` });

Errors

API failures throw AutopilotMailError with status, code, and requestId properties:

import { AutopilotMailError } from "@autopilotstartup/mail";

try {
  await mail.emails.send(message);
} catch (error) {
  if (error instanceof AutopilotMailError) {
    console.error(error.status, error.code, error.message);
  }
}