HTTP client

import { Flaresend } from '@flaresend/client';

const flaresend = new Flaresend({
  apiKey: process.env.FLARESEND_API_KEY!,
  baseUrl: 'https://mailer.example.com',
});

OptionsCopy Anchor Link

Every request sends Authorization: Bearer <apiKey> and Accept: application/json, and JSON bodies with Content-Type: application/json.

RetriesCopy Anchor Link

• The wait between tries is exponential backoff with jitter: about 0.5 s, 1 s, 2 s and so on, capped at 8 s.
• If the response has a Retry-After header, the client waits that long instead. If Retry-After is more than 60 seconds, it doesn't wait and throws the error.
• 429 daily_limit_exceeded is never retried: waiting a few seconds won't help.
• Any other 4xx is thrown at once.

IdempotencyCopy Anchor Link

Every emails.send call gets an idempotency key, sent as the Idempotency-Key header. The key is, in order:

1. opts.idempotencyKey, the second argument.
2. input.idempotencyKey, in the email itself.
3. A random auto_<uuid> made for this call.

The same key is reused for that call's retries, so a timeout followed by a retry sends one email, not two. The random key does not protect you from your own code calling send twice. For that, pass a key that is stable for the thing you're sending:

await flaresend.emails.send(input, { idempotencyKey: `welcome-${user.id}` });

A second call with the same key and the same content returns the first email with idempotent: true. The same key with different content throws 409 idempotency_payload_mismatch. Keys don't expire. See Idempotency.

emails.sendBatch works the same way with one key for the whole batch; the mailer stores it per item as <key>:<index>.

MethodsCopy Anchor Link

Paginated methods return { data, nextCursor }. Pass nextCursor back as cursor for the next page; it is null on the last page. Other list methods return a plain array.

me()Copy Anchor Link

me(): Promise<MeRecord>

GET /v1/me. Returns { project: { id, slug, name }, key: { id, name, mode } }. A cheap way to check the key and URL work.

emailsCopy Anchor Link

opts for send is { idempotencyKey?: string }. For sendBatch it is { idempotencyKey?: string; dryRun?: boolean }.

list takes { limit, cursor, status, to, from, q, tag, since, until }. to matches any of to, cc and bcc. q searches the subject. tag is key:value.

const page = await flaresend.emails.list({ status: 'bounced', since: '2026-09-01T00:00:00Z', limit: 50 });

eventsCopy Anchor Link

query is { limit, cursor, type, emailId, since }.

domainsCopy Anchor Link

apiKeysCopy Anchor Link

webhooksCopy Anchor Link

templatesCopy Anchor Link

analyticsCopy Anchor Link

query is { range: '7d' | '30d' | '90d', interval: 'day' | 'hour' }, defaults 7d and day.

contactsCopy Anchor Link

audiencesCopy Anchor Link

broadcastsCopy Anchor Link

HelpersCopy Anchor Link

attachmentFromBytes(filename, bytes, type?)Copy Anchor Link

Builds an attachment from an ArrayBuffer or Uint8Array. The API needs attachment content as base64; this does the encoding without Buffer, so it works in Workers and browsers too.

import { attachmentFromBytes } from '@flaresend/client';

const pdf = new Uint8Array(await file.arrayBuffer());
await flaresend.emails.send({
  from: 'Acme <billing@acme.com>',
  to: 'ada@example.com',
  subject: 'Your invoice',
  text: 'Your invoice is attached.',
  attachments: [attachmentFromBytes('invoice.pdf', pdf, 'application/pdf')],
});

bytesToBase64(bytes) is exported too, if you only need the encoding.

Typed templatesCopy Anchor Link

Pass a map of template name to data type as the type argument of send, and data is checked against the template you name:

type Templates = {
  welcome: { name: string; appName: string; loginUrl: string };
  'magic-link': { loginUrl: string; expiresInMinutes?: number };
};

await flaresend.emails.send<Templates>({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome',
  data: { name: 'Ada', appName: 'Acme', loginUrl: 'https://acme.com/login' },
});

TypedSend<Templates> is the input type on its own. See Typed templates.

Exported typesCopy Anchor Link

The package re-exports the request and response types from @flaresend/types, including SendEmailInput, SendEmailResult, EmailRecord, EmailContent, EventRecord, ListResponse, BatchResult, BatchDryRunResult, WebhookRecord, WebhookPayload, TemplateRecord, ContactRecord, AudienceRecord, BroadcastRecord and AnalyticsResult.