JavaScript SDK
gentlemail is the official SDK for JavaScript and TypeScript. It wraps the API, verifies webhooks, and types everything both send. It has no dependencies and runs on Cloudflare Workers, Node 20+, Deno and Bun.
npm install gentlemailIt works with GentleMail 0.3.0 and later.
The SDK has its own versions, apart from the app’s. This page describes the latest one, and each section says which version added it, so you can tell what the version you installed can do (npm ls gentlemail prints it). What each version changed is in the SDK changelog, and the docs of an older version are its README on npm.
Connect
Section titled “Connect”Since 0.1.0
Create a key in Admin → API & webhooks with the access the program needs (see API keys), and keep it in your secrets.
import { GentleMail } from "gentlemail";
const mail = new GentleMail({ url: "https://mail.example.com", // your GentleMail apiKey: env.GENTLEMAIL_KEY,});Since 0.1.0
const sent = await mail.send({ from: "support@example.com", to: ["Ada Lovelace <ada@example.org>"], cc: { address: "team@example.com", name: "Team" }, subject: "Your order has shipped", text: "It should arrive on Friday.", html: "<p>It should arrive on <b>Friday</b>.</p>", attachments: [{ filename: "invoice.pdf", content: pdfBytes, content_type: "application/pdf" }],});// { id, thread_id, from, status: "sent" }Every send field is supported. Attachment content can be bytes (Uint8Array, ArrayBuffer) or a base64 string; the SDK encodes bytes for you.
Read and file
Section titled “Read and file”Since 0.1.0
const mailboxes = await mail.mailboxes.list(); // with this key's permissions on each
const unread = await mail.messages.list({ mailbox: "support@example.com", // or leave out for every mailbox the key can read folder: "inbox", // inbox, sent, archive, spam, trash or all unread: true, since: new Date(Date.now() - 86_400_000), limit: 50,});
const message = await mail.messages.get(unread[0].id); // adds text and htmlawait mail.messages.update(message.id, "read"); // read, unread, star, unstar, archive, trash, spam, inboxmessage.html is the HTML exactly as received. Sanitise it before you show it in a browser.
Since 0.1.0
messages.reply() answers from the message’s own mailbox, in its thread, to its sender. Pass any message: from get(), list() or a webhook event’s data. The key needs Read and Send on the mailbox.
await mail.messages.reply(message, { text: "Thanks, we're on it.", quote: true });Attachments
Section titled “Attachments”Since 0.1.0
attachments.download() takes an attachment’s id or url and returns the Response, so you can stream it or read it:
const file = await mail.attachments.download(message.attachments[0].url);await env.FILES.put(message.attachments[0].filename, file.body); // stream to R2Webhooks
Section titled “Webhooks”Since 0.1.0
verifyWebhook() checks the signature and refuses deliveries older than five minutes, then returns the typed event. Give it the incoming Request:
import { GentleMail, verifyWebhook } from "gentlemail";
export default { async fetch(request: Request, env: Env) { const event = await verifyWebhook(request, env.WEBHOOK_SECRET).catch(() => null); if (!event) return new Response("Bad signature", { status: 401 });
switch (event.event) { case "message.received": { const mail = new GentleMail({ url: env.GENTLEMAIL_URL, apiKey: env.GENTLEMAIL_KEY }); await mail.messages.reply(event.data, { text: "Got it, thanks!" }); break; } case "ping": // "Send test" on the webhook's page break; } return new Response("OK"); },};With Express or Node’s http, pass the raw body and the headers instead. The body must be exactly what arrived, so don’t parse it first:
app.post("/mail", express.raw({ type: "application/json" }), async (req, res) => { const event = await verifyWebhook({ body: req.body, headers: req.headers }, process.env.WEBHOOK_SECRET!); // … res.send("OK");});The same event can arrive twice: skip event.ids you’ve already handled. Change the age limit with { tolerance: seconds }.
Errors
Section titled “Errors”Since 0.1.0
| Thrown | When | Fields |
|---|---|---|
GentleMailError |
The API answered with an error | status, code (see Errors), message |
WebhookVerificationError |
A delivery was refused | reason: bad_signature, expired, missing_headers or invalid_json |
import { GentleMailError } from "gentlemail";
try { await mail.send({ from: "sales@example.com", to: "ada@example.org", text: "Hi" });} catch (e) { if (e instanceof GentleMailError && e.code === "mailbox_not_allowed") { // this key can't send from sales@ } else throw e;}