# Mailfully

> Documentation for Mailfully.

## Documentation

- [Introduction](https://mailfully.com/docs/introduction.md): Mailfully is an HTTP API for sending transactional email, with delivery tracking, webhooks, and a Node SDK.
- [Quickstart](https://mailfully.com/docs/quickstart.md): Send your first email through the Mailfully API — from API key to delivered.
- [Authentication](https://mailfully.com/docs/concepts/authentication.md): How bearer API keys work, which scopes they can carry, and how to read 401 vs 403 responses.
- [How sending works](https://mailfully.com/docs/concepts/how-sending-works.md): Why sends return 202, which checks run synchronously, and how a message moves through its nine-status lifecycle.
- [Idempotency](https://mailfully.com/docs/concepts/idempotency.md): Use the Idempotency-Key header to retry sends safely without dispatching duplicate email.
- [Rate limits and quotas](https://mailfully.com/docs/concepts/rate-limits.md): How the send-route rate limit and the per-plan send quotas interact, and which response headers to build retry logic on.
- [Errors](https://mailfully.com/docs/concepts/errors.md): The Mailfully error envelope, the catalog of error types by HTTP status, and how to handle them in code.
- [Verify a domain](https://mailfully.com/docs/guides/verify-a-domain.md): Add a sending domain, publish its DNS records, and verify it before sending live email.
- [Templates](https://mailfully.com/docs/guides/templates.md): Store reusable HTML and text bodies with {{variable}} placeholders and render them when a send is accepted.
- [Scheduled sends](https://mailfully.com/docs/guides/scheduled-sends.md): Schedule an email up to 90 days ahead with scheduled_at, then reschedule or cancel it before it dispatches.
- [Batch sending](https://mailfully.com/docs/guides/batch-sending.md): Send up to 100 emails in one request with all-or-nothing acceptance.
- [Webhooks](https://mailfully.com/docs/guides/webhooks.md): Get delivery, bounce, and complaint events pushed to your endpoint as signed HTTP callbacks, with automatic retries and dead-letter replay.
- [Suppressions](https://mailfully.com/docs/guides/suppressions.md): How addresses land on your suppression list, what happens when you send to them, and how to list, add, and remove entries.
- [Analytics](https://mailfully.com/docs/guides/analytics.md): Query daily send and engagement rollups by day, tag, and recipient domain, plus Gmail spam-rate reputation for your sending domains.
- [Node.js SDK](https://mailfully.com/docs/sdks/node.md): Install @mailfully/node, construct the client, handle the { data, error } result tuple, and map every SDK method to its API endpoint.

## API Reference

- [API overview](https://mailfully.com/docs/api-reference/overview.md): Base URL, authentication, error format, idempotency, rate limits, and pagination for the Mailfully API.
- [Send an email](https://mailfully.com/docs/api-reference/emails/send.md): Validate and accept a transactional email, returning 202 Accepted with the message id once the message row is persisted and (unless every recipient is…
- [Send a batch of emails](https://mailfully.com/docs/api-reference/emails/send-batch.md): Accept a JSON array of 1–100 email objects, each identical to the single send body.
- [List emails](https://mailfully.com/docs/api-reference/emails/list.md): List accepted messages, newest first, with keyset pagination.
- [Retrieve an email](https://mailfully.com/docs/api-reference/emails/get.md): Retrieve one accepted message by id, including its rendered bodies.
- [Reschedule an email](https://mailfully.com/docs/api-reference/emails/reschedule.md): Move the send time of a future-dated, still-queued message.
- [Cancel a scheduled email](https://mailfully.com/docs/api-reference/emails/cancel.md): Cancel a still-queued send. Only a queued message is cancellable; a canceled send is never sent and never billed.
- [List email events](https://mailfully.com/docs/api-reference/emails/list-events.md): Return the event timeline for one message, oldest first.
- [Add a domain](https://mailfully.com/docs/api-reference/domains/create.md): Register a custom sending domain. Provisions the SES Easy-DKIM identity, a custom MAIL FROM subdomain, and a per-domain configuration set, then returns the…
- [List domains](https://mailfully.com/docs/api-reference/domains/list.md): List all of the organization's sending domains. This endpoint is not paginated and list rows do not include DNS records.
- [Retrieve a domain](https://mailfully.com/docs/api-reference/domains/get.md): Retrieve one sending domain and its DNS records, recomputed from the persisted row. A tracking-enabled domain additionally includes the tracking CNAME last.
- [Verify a domain](https://mailfully.com/docs/api-reference/domains/verify.md): Trigger an on-demand verification poll: Mailfully queries SES for the current DKIM and MAIL FROM status, runs the 72-hour verification state machine, persists…
- [Update domain tracking](https://mailfully.com/docs/api-reference/domains/update-tracking.md): Toggle open and click tracking for a domain — a single boolean covers both.
- [Create a template](https://mailfully.com/docs/api-reference/templates/create.md): Create a reusable template. At least one of html or text is required. Templates carry no subject — the subject comes from the send request.
- [List templates](https://mailfully.com/docs/api-reference/templates/list.md): List all of the organization's templates. This endpoint is not paginated and rows are returned in unspecified order.
- [Retrieve a template](https://mailfully.com/docs/api-reference/templates/get.md): Retrieve one template by id. Org-scoped; a cross-org or unknown id returns 404. Requires the send or read:emails scope.
- [Update a template](https://mailfully.com/docs/api-reference/templates/update.md): Partially update a template; omitted fields are left untouched.
- [Delete a template](https://mailfully.com/docs/api-reference/templates/delete.md): Permanently delete a template. Already-accepted sends are unaffected; the id is not reserved and future sends referencing it will 404. Requires the send scope.
- [Create a webhook endpoint](https://mailfully.com/docs/api-reference/webhooks/create.md): Register an http(s) endpoint to receive email events. The signingsecret (whsec…) is returned once, only here — store it to verify delivery signatures.
- [List webhook endpoints](https://mailfully.com/docs/api-reference/webhooks/list.md): List all of the organization's webhook endpoints. Not paginated; the signingsecret is never included.
- [Retrieve a webhook endpoint](https://mailfully.com/docs/api-reference/webhooks/get.md): Retrieve one webhook endpoint by id (no signingsecret).
- [Delete a webhook endpoint](https://mailfully.com/docs/api-reference/webhooks/delete.md): Delete a webhook endpoint. Requires the manage:webhooks scope, which is a dashboard-session scope and cannot be granted to API keys today: every mf API key…
- [List webhook deliveries](https://mailfully.com/docs/api-reference/webhooks/list-deliveries.md): List one endpoint's delivery attempts, newest first, with keyset pagination (default limit 50).
- [List dead-lettered deliveries](https://mailfully.com/docs/api-reference/webhooks/list-dead-letters.md): List the organization's dead-lettered webhook deliveries (events whose 7-attempt retry schedule was exhausted), newest first, with keyset pagination (default…
- [Replay a dead-lettered delivery](https://mailfully.com/docs/api-reference/webhooks/replay-dead-letter.md): Re-enqueue a dead-lettered delivery as a fresh attempt-1 job pinned to that endpoint (which is re-enabled if it was auto-disabled).
- [List suppressions](https://mailfully.com/docs/api-reference/suppressions/list.md): List the organization's suppressed addresses, newest first, with keyset pagination. Suppressions are org-global (not partitioned by environment).
- [Add a suppression](https://mailfully.com/docs/api-reference/suppressions/create.md): Manually suppress an address. The email is normalized (trim().toLowerCase()) before storage; the format is not validated.
- [Remove a suppression](https://mailfully.com/docs/api-reference/suppressions/delete.md): Remove a suppression by id. If the row was synced to the account-level SES suppression list and no other organization still suppresses the address, it is…
- [Get daily analytics](https://mailfully.com/docs/api-reference/analytics/daily.md): Return exact per-day delivery counters over a date window.
- [Get analytics by tag](https://mailfully.com/docs/api-reference/analytics/by-tag.md): Return per-(tag value, day) counters. Rollups are keyed by tag value, not name.
- [Get analytics by domain](https://mailfully.com/docs/api-reference/analytics/by-domain.md): Return per-(recipient domain, day) counters.
- [Get external reputation](https://mailfully.com/docs/api-reference/analytics/external-reputation.md): Return the latest Gmail Postmaster user-reported spam-rate observation per verified sending domain, plus the worst rate across domains.
- [Create an API key](https://mailfully.com/docs/api-reference/api-keys/create.md): Mint a new API key. The full plaintext key is returned once, only here.
- [List API keys](https://mailfully.com/docs/api-reference/api-keys/list.md): List the organization's API keys for the current environment, newest first. Each key is masked to prefix and last4; the plaintext and hash are never returned.
- [Rotate an API key](https://mailfully.com/docs/api-reference/api-keys/rotate.md): Rotate an active API key: mint a successor copying the old key's name, scopes, domain, and environment, and stamp the old key to stop authenticating in 24…
- [Revoke an API key](https://mailfully.com/docs/api-reference/api-keys/revoke.md): Revoke an API key. Idempotent: an active key is stamped revokedat = now and rejected immediately thereafter; a key that already has a revokedat (a prior revoke…