# Docs

- Documentation: Guides and concepts

  - **Getting started**
  - [Introduction](/docs): Flaresend is a transactional email API that runs in your own Cloudflare account.
  - [Quickstart](/docs/quickstart): Send your first email with Flaresend and check that it was delivered.
  - [How it works](/docs/how-it-works): What happens to an email between your API call and the recipient's inbox, and how its status gets back to you.
  - Send with…
    - [Send emails with Node.js](/docs/send-with/nodejs): Use @flaresend/client to send email from any Node.js app.
    - [Send emails with Next.js](/docs/send-with/nextjs): Send email from a Next.js Route Handler or Server Action with @flaresend/client.
    - [Send emails with Cloudflare Workers](/docs/send-with/cloudflare-workers): Call the mailer over a service binding with no API key, or over HTTP from any Worker.
    - [Send emails with Hono](/docs/send-with/hono): Send email from a Hono app on Cloudflare Workers, over a service binding or over HTTP.
    - [Send emails with Bun](/docs/send-with/bun): Use @flaresend/client from a Bun script or server.
    - [Send emails with Python](/docs/send-with/python): Call the Flaresend REST API from Python with requests.
    - [Send emails with Go](/docs/send-with/go): Call the Flaresend REST API from Go with net/http.
    - [Send emails with PHP](/docs/send-with/php): Call the Flaresend REST API from PHP with the curl extension.
    - [Send emails with Ruby](/docs/send-with/ruby): Call the Flaresend REST API from Ruby with net/http.
    - [Send emails with cURL](/docs/send-with/curl): Call the Flaresend REST API from the command line.

  - **Sending**
  - [Sending emails](/docs/emails/sending): Senders, recipients, bodies, and every check an email goes through before it is queued.
  - [Attachments](/docs/emails/attachments): Attach files as base64, including inline images referenced from the HTML.
  - [Custom headers](/docs/emails/headers): Add your own email headers, within the rules Cloudflare Email Service enforces.
  - [Tags](/docs/emails/tags): Label emails with your own key-value pairs, then filter by them and read them in webhooks.
  - [Scheduling](/docs/emails/scheduling): Send an email later, up to 30 days ahead, and cancel or move it before it goes out.
  - [Batch sending](/docs/emails/batch): Send up to 100 different emails in one request and get a result for each.
  - [Idempotency](/docs/emails/idempotency): Retry a send as often as you like without the email going out twice.
  - [Test mode](/docs/emails/test-mode): Use an fs_test_ key to exercise your integration without sending real email.
  - [Open and click tracking](/docs/emails/tracking): Count opens with a tracking pixel and clicks with rewritten links.
  - [Statuses and events](/docs/emails/statuses): What each email and recipient status means, how they change, and the timeline events behind them.

  - **Templates**
  - [Templates](/docs/templates): Send by template name and data instead of building HTML in every app.
  - [Built-in templates](/docs/templates/built-in): The five React Email templates that ship with the mailer, their data, and how to add your own.
  - [Custom templates](/docs/templates/custom): HTML templates with variables, stored per project and edited without a deploy.
  - [Typed templates](/docs/templates/typed): Let TypeScript check that each template gets the data it needs.

  - **Webhooks**
  - [Webhooks](/docs/webhooks): Get a signed HTTP request every time one of your emails is sent, delivered, bounced, opened or clicked.
  - [Event types](/docs/webhooks/event-types): Every event a webhook can receive, when it fires, and what its data contains.
  - [Verify signatures](/docs/webhooks/verify): Check that a webhook request really came from your Flaresend mailer and was not changed on the way.
  - [Delivery and retries](/docs/webhooks/retries): What counts as a successful delivery, how failed deliveries are retried, and how to see every attempt.

  - **Contacts & broadcasts**
  - [Contacts](/docs/contacts/contacts): Store the people you send broadcasts to, with their names, your own data and their unsubscribe state.
  - [Audiences](/docs/contacts/audiences): Named lists of contacts. A broadcast is always sent to one audience.
  - [Broadcasts](/docs/contacts/broadcasts): Send one personalized email to every subscribed contact in an audience. For small, opted-in lists only.
  - [Unsubscribe links](/docs/contacts/unsubscribe): Every broadcast email carries a signed, per-contact unsubscribe link and the List-Unsubscribe headers mail clients use for their own button.

  - **Deliverability**
  - [Domains](/docs/deliverability/domains): Set up a sending domain in Cloudflare Email Service, with SPF, DKIM and DMARC, and let Flaresend check its status.
  - [Suppressions](/docs/deliverability/suppressions): Addresses Flaresend refuses to send to, because they bounced hard, complained, or were added by hand.
  - [Best practices](/docs/deliverability/best-practices): Practical steps that keep your email out of spam folders, and how to use Flaresend's data to spot problems early.

  - **Projects**
  - [Projects](/docs/projects): A project is one app or service that sends email. It owns its keys, domains, limits, templates, webhooks and contacts.
  - [API keys](/docs/api-keys): Project keys authenticate REST calls. Live keys send; test keys record the email and never send it.
  - [Dashboard](/docs/dashboard): A tour of the Flaresend dashboard, the admin UI you deploy next to the mailer and protect with Cloudflare Access.
  - [Limits](/docs/limits): Every size, count and rate limit in Flaresend, in one place, with where it is enforced.

  - **SDK**
  - [@flaresend/client](/docs/sdk): The official TypeScript client. Sends over HTTP from any runtime with fetch, or over RPC from Cloudflare Workers.
  - [HTTP client](/docs/sdk/http): Reference for the Flaresend class. Every namespace and method, with retries and idempotency explained.
  - [RPC client](/docs/sdk/rpc): Send from another Cloudflare Worker over a service binding. No API key, no public network hop.
  - [Webhook helpers](/docs/sdk/webhooks): Verify and sign Flaresend-Signature headers with Web Crypto, in any JavaScript runtime.
  - [Error handling](/docs/sdk/errors): Both clients throw FlaresendError, with the same type, code, message and param the API returns.

  - **Help**
  - [Troubleshooting](/docs/troubleshooting): The problems people hit most often, what causes each one, and how to fix it.
  - [FAQ](/docs/faq): Short answers to common questions about Flaresend.
- API Reference: Every HTTP endpoint

  - **Overview**
  - [Introduction](/docs/api-reference): How the Flaresend HTTP API works: base URL, requests, responses and request IDs.
  - [Authentication](/docs/api-reference/authentication): Project API keys, test keys and the admin key.
  - [Errors](/docs/api-reference/errors): The error body, the eight error types, and every error code the API returns.
  - [Pagination](/docs/api-reference/pagination): Walk through long lists with limit, cursor and nextCursor.
  - [Rate limits](/docs/api-reference/rate-limits): The per-minute send limit, the daily limit, and how to handle 429 responses.

  - **Endpoints**
  - Emails
    - [Send an email](/docs/api-reference/emails/send): Queue one email for delivery. Returns as soon as the email is stored, without waiting for Cloudflare.
    - [Send a batch](/docs/api-reference/emails/send-batch): Queue up to 100 emails in one request, with a result for each.
    - [List emails](/docs/api-reference/emails/list): Search the project's emails by status, recipient, sender, subject, tag and date.
    - [Retrieve an email](/docs/api-reference/emails/retrieve): Get one email with its recipients and full event timeline.
    - [Retrieve email content](/docs/api-reference/emails/content): Get the stored HTML, text, headers and attachment list of an email.
    - [Reschedule an email](/docs/api-reference/emails/update): Move a scheduled email to a new send time.
    - [Cancel an email](/docs/api-reference/emails/cancel): Cancel a scheduled email before it is sent.
  - Events
    - [List events](/docs/api-reference/events/list): Every timeline event in the project, newest first.
  - Domains
    - [List domains](/docs/api-reference/domains/list): The project's sending domains, their default senders and their status in Cloudflare.
  - API keys
    - [List API keys](/docs/api-reference/api-keys/list): Every API key of the project, including revoked and expired ones.
    - [Retrieve the current key](/docs/api-reference/api-keys/me): Find out which project and key a request is using. A cheap way to check a key works.
  - Webhooks
    - [Create a webhook](/docs/api-reference/webhooks/create): Register an endpoint that receives a signed POST for the email events you pick.
    - [List webhooks](/docs/api-reference/webhooks/list): Every webhook in the project, oldest first.
    - [Retrieve a webhook](/docs/api-reference/webhooks/retrieve): One webhook by ID, without its secret.
    - [Update a webhook](/docs/api-reference/webhooks/update): Change a webhook's URL, events, or turn it on and off.
    - [Delete a webhook](/docs/api-reference/webhooks/delete): Remove a webhook and its delivery history.
    - [Send a test event](/docs/api-reference/webhooks/test): Deliver a fake email.delivered event to one webhook, to check your endpoint.
    - [Rotate a webhook secret](/docs/api-reference/webhooks/rotate-secret): Replace a webhook's signing secret and get the new one.
    - [List webhook deliveries](/docs/api-reference/webhooks/deliveries): The delivery attempts for one webhook, newest first.
  - Templates
    - [Create a template](/docs/api-reference/templates/create): Store a template in the project, with Mustache-style variables.
    - [List templates](/docs/api-reference/templates/list): The project's stored templates, followed by the built-in templates they don't replace.
    - [Retrieve a template](/docs/api-reference/templates/retrieve): One template by name. Built-in templates come back rendered with their example data.
    - [Update a template](/docs/api-reference/templates/update): Save a new version of a stored template.
    - [Delete a template](/docs/api-reference/templates/delete): Remove a stored template and all its versions.
    - [List template versions](/docs/api-reference/templates/versions): Every saved version of a stored template, newest first.
    - [Restore a template version](/docs/api-reference/templates/restore): Bring back an older version of a stored template as a new version.
    - [Render a template](/docs/api-reference/templates/render): Preview what a template produces for some data, without sending anything.
  - Analytics
    - [Retrieve analytics](/docs/api-reference/analytics/retrieve): Counts per day or hour, delivery and bounce rates, delivery time, top tags and top bouncing domains.
  - Contacts
    - [Create a contact](/docs/api-reference/contacts/create): Add a contact to the project, or update it if a contact with that email already exists.
    - [List contacts](/docs/api-reference/contacts/list): Page through the project's contacts, newest first, with an optional search.
    - [Retrieve a contact](/docs/api-reference/contacts/retrieve): Get one contact by its ID.
    - [Update a contact](/docs/api-reference/contacts/update): Change a contact's name, data or subscription status.
    - [Delete a contact](/docs/api-reference/contacts/delete): Remove a contact and take it out of every audience.
    - [Import contacts](/docs/api-reference/contacts/import): Create or update up to 5,000 contacts in one request.
  - Audiences
    - [Create an audience](/docs/api-reference/audiences/create): Create a named list of contacts that a broadcast can be sent to.
    - [List audiences](/docs/api-reference/audiences/list): Get every audience in the project, sorted by name.
    - [Retrieve an audience](/docs/api-reference/audiences/retrieve): Get one audience and its contact count.
    - [Update an audience](/docs/api-reference/audiences/update): Rename an audience.
    - [Delete an audience](/docs/api-reference/audiences/delete): Delete an audience. The contacts in it are kept.
    - [List audience contacts](/docs/api-reference/audiences/list-contacts): Page through the contacts in one audience, newest first.
    - [Add contacts to an audience](/docs/api-reference/audiences/add-contacts): Put up to 5,000 existing contacts into an audience.
    - [Remove contacts from an audience](/docs/api-reference/audiences/remove-contacts): Take up to 5,000 contacts out of an audience without deleting them.
  - Broadcasts
    - [Create a broadcast](/docs/api-reference/broadcasts/create): Create a draft email to one audience. Nothing is sent until you call send.
    - [List broadcasts](/docs/api-reference/broadcasts/list): Get every broadcast in the project, newest first.
    - [Retrieve a broadcast](/docs/api-reference/broadcasts/retrieve): Get one broadcast with a count of its emails by status.
    - [Update a broadcast](/docs/api-reference/broadcasts/update): Change a draft broadcast's audience, sender, subject or body.
    - [Delete a broadcast](/docs/api-reference/broadcasts/delete): Delete a broadcast that is not scheduled or sending.
    - [Send a broadcast](/docs/api-reference/broadcasts/send): Start a draft broadcast now, or schedule it for later.
    - [Cancel a broadcast](/docs/api-reference/broadcasts/cancel): Stop a draft, scheduled or sending broadcast.

  - **Admin**
  - Admin API
    - [Admin API](/docs/api-reference/admin): Manage projects, API keys and suppressions, and act on any project, with the mailer's admin key.
    - [Create a project](/docs/api-reference/admin/create-project): Create a project, the unit that owns API keys, sending domains, emails and settings.
    - [List projects](/docs/api-reference/admin/list-projects): Every project on the mailer, oldest first, disabled ones included.
    - [Retrieve a project](/docs/api-reference/admin/retrieve-project): Get one project's settings by its slug.
    - [Update a project](/docs/api-reference/admin/update-project): Change a project's settings. Only the fields you send are changed.
    - [Disable a project](/docs/api-reference/admin/disable-project): Stop a project from sending. Nothing is deleted, and it can be enabled again.
    - [Create an API key](/docs/api-reference/admin/create-api-key): Mint a live or test key for a project. The full key is returned once and never stored.
    - [List API keys](/docs/api-reference/admin/list-api-keys): Every API key, across all projects or for one project, newest first.
    - [Rename an API key](/docs/api-reference/admin/rename-api-key): Change a key's label. The key itself does not change.
    - [Revoke an API key](/docs/api-reference/admin/revoke-api-key): Stop a key from working, immediately and for good.
    - [Set up a domain](/docs/api-reference/admin/setup-domain): Onboard one of a project's domains in Cloudflare Email Sending, with its DNS records and delivery events.
    - [List emails across projects](/docs/api-reference/admin/list-emails): Search the email log of every project, or one project by slug.
    - [Resend an email](/docs/api-reference/admin/resend-email): Send a stored email again as a new email, from any project.
    - [List suppressions](/docs/api-reference/admin/list-suppressions): Addresses Flaresend refuses to send to, in alphabetical order.
    - [Add a suppression](/docs/api-reference/admin/add-suppression): Block an address from receiving email from every project.
    - [Remove a suppression](/docs/api-reference/admin/remove-suppression): Let an address receive email again.
    - [Retrieve stats](/docs/api-reference/admin/stats): Email counts by status for every project, for today, the last 7 days and the last 30 days.
    - [Post a fake delivery event](/docs/api-reference/admin/dev-events): Run a hand-made Cloudflare delivery event through the events pipeline. Development only.
- Self-hosting: Run Flaresend on your account

  - **Deploy**
  - [Overview](/docs/self-hosting): What you deploy to run Flaresend, which Cloudflare products it uses, and what you need before you start.
  - [Deploy](/docs/self-hosting/deploy): Set up Flaresend in your Cloudflare account, from an empty account to your first API key.
  - [Configuration](/docs/self-hosting/configuration): Every variable, secret and binding the mailer Worker reads, and what changes when you set it.
  - [Dashboard](/docs/self-hosting/dashboard): Deploy the admin dashboard as its own Worker, protected by Cloudflare Access.

  - **Operate**
  - [CLI](/docs/self-hosting/cli): The flaresend command line tool for projects, API keys, emails, suppressions, stats and test sends.
  - [Architecture](/docs/self-hosting/architecture): How the mailer Worker stores data, uses its queues, retries failures and what the cron job does.
  - [Local development](/docs/self-hosting/local-development): Run the mailer on your machine, fake delivery events, and run the tests.
  - [CI and releases](/docs/self-hosting/ci): What the two GitHub Actions workflows do, the secrets they need, and how client releases are versioned.
  - [Upgrading](/docs/self-hosting/upgrading): Update a running Flaresend deployment to a newer version of the repo.