Click here to confirm.
", text: "Confirm your email: https://app.example.com/confirm?t=abc", }); console.log(res.id, res.status); ``` Every field you can set on the email: | Field | Type | Notes | | - | - | - | | `from` | string | Required. Must use a verified domain. | | `to` | string | Required. One address. | | `toName` | string | Display name for the recipient. | | `cc`, `bcc` | string\[] | Extra recipients. | | `subject` | string | Subject line. | | `html`, `text` | string | Body. Send one or both. | | `replyTo` | string | Where replies go. | | `headers` | object | Extra message headers, for example `{ "List-Unsubscribe": "<...>" }`. | | `scheduledAt` | string | An ISO 8601 date-time. The email is sent at that time. | | `templateId`, `templateName` | string | Send a stored template instead of `html`. | | `variables` | object | Values for the template placeholders. | | `attachments` | array | See [Attachments](#attachments). | The SDK converts camelCase names to the API's snake\_case names for you. ### Send with a template ```js theme={null} await sendflit.send({ from: "billing@yourdomain.com", to: "user@example.com", templateName: "receipt", variables: { order_id: "1042", total: "$24.00" }, }); ``` ## Attachments Each attachment is an object with a `filename`, `content` and an optional `contentType`. A string is encoded as UTF-8 and a `Buffer` or `Uint8Array` is encoded as-is. ```js theme={null} import { readFile } from "node:fs/promises"; await sendflit.send({ from: "billing@yourdomain.com", to: "user@example.com", subject: "Your receipt", html: "Your receipt is attached.
", attachments: [ { filename: "receipt.pdf", content: await readFile("./receipt.pdf"), contentType: "application/pdf", }, { filename: "notes.txt", content: "Thanks for your order." }, ], }); ``` Limits: * Up to 10 attachments per message. * Up to 10 MB per attachment. Larger files are rejected with `422`. ## Safe retries with idempotency keys A network timeout doesn't tell you whether the server sent the email. Pass an idempotency key so a retry can't send it twice. ```js theme={null} const key = `order-confirmation-${orderId}`; await sendflit.send( { from: "orders@yourdomain.com", to: buyer.email, subject: "Order confirmed", html }, key, ); ``` If you send the same key with the same body again, the API returns the original result and does not send a second email. If you reuse a key with a different body, the API rejects the request with `409`. That means your code has a bug, so generate a new key for a new email. For the full rules, see [Idempotency](/guides/idempotency). ## Send a batch `batch` sends up to 100 emails in one request. The response has a `results` array with one entry per email, in the order you sent them, and a `count`. ```js theme={null} const { results } = await sendflit.batch([ { from: "news@yourdomain.com", to: "a@example.com", subject: "Digest", html: "Hi A
" }, { from: "news@yourdomain.com", to: "b@example.com", subject: "Digest", html: "Hi B
" }, ], `digest-${today}`); ``` The second argument is an optional idempotency key that covers the whole batch. An empty array, or more than 100 emails, throws a `TypeError` or `RangeError` before any request is made. See [Batch sending](/guides/batch-sending). ## Manage emails ```js theme={null} // List recent emails. Use limit and offset to page through results. const page = await sendflit.listEmails({ limit: 20, offset: 0 }); // Look up one email by its id. const email = await sendflit.getEmail("em_123"); // Cancel an email that is scheduled but not sent yet. await sendflit.cancelEmail("em_123"); ``` `cancelEmail` removes an email that is still scheduled. If the email has already been sent, the API returns an error, which the SDK throws as a `SendFlitError` with the status and body. ## Domains Add the domain, publish the DNS records it returns, then verify it. You can send only from a verified domain. ```js theme={null} const domain = await sendflit.addDomain("yourdomain.com"); console.log(domain.id); const all = await sendflit.listDomains(); // Run after the DNS records are live. Changes can take time to propagate. const status = await sendflit.verifyDomain(domain.id); ``` For the DNS records and the dashboard steps, see [Domains](/concepts/domains). ## Suppressions Suppressed addresses never receive email from your account. Add an address when a recipient unsubscribes or complains. ```js theme={null} await sendflit.suppress({ email: "user@example.com", reason: "unsubscribe" }); ``` `suppress` takes one object. `reason` is optional and defaults to `"unsubscribe"`. See [Emails](/concepts/emails) for how suppressions interact with sending. ## Usage and health ```js theme={null} const usage = await sendflit.usage(); // usage counts for your account const ok = await sendflit.health(); // calls GET /health ``` `health` doesn't need a valid key. Use it in a readiness probe or a startup check. ## Verify webhooks SendFlit signs every webhook request. The signature is an HMAC-SHA256 of the raw request body, sent in the `X-Sendflit-Signature` header as `sha256=