# Mailfully > Documentation for Mailfully. ## Documentation - [Introduction](https://mailfully.com/docs/introduction.md): Mailfully is an API for sending and receiving 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 in test mode, then verify a domain to go live. - [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 ten-status lifecycle. - [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. - [API key security](https://mailfully.com/docs/concepts/api-key-security.md): Choose the narrowest scope, keep test and live keys apart, store secrets outside your repository, and rotate on a schedule. - [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. - [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. - [Quotas and plan limits](https://mailfully.com/docs/concepts/quotas-and-plan-limits.md): What each plan includes before any limit fires: sent and received volume, overage ceiling, retention window, and spend cap, plus how the sending-domain cap works. - [Idempotency](https://mailfully.com/docs/concepts/idempotency.md): Use the Idempotency-Key header to retry sends safely without dispatching duplicate email. - [Policies](https://mailfully.com/docs/concepts/policies.md): The sending standards, email categories, and content rules every Mailfully account is held to, what happens when an account breaches them, and how to appeal. - [Test mode](https://mailfully.com/docs/guides/test-mode.md): Send with an mf_test_ key to exercise the real send path without delivering mail, force per-recipient bounces and complaints, and read back which recipient was affected. - [Choosing a sending feature](https://mailfully.com/docs/guides/choosing-a-sending-feature.md): Pick between a single send, a batch, a scheduled send, a template, and a marketing send, and see which ones combine. - [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. - [Attachments](https://mailfully.com/docs/guides/attachments.md): Attach files to a send with base64 content, embed inline images with cid, and stay inside the 40 MiB message ceiling. - [Marketing emails and unsubscribe](https://mailfully.com/docs/guides/unsubscribe-links.md): What a marketing send adds to your message, the checks it must pass, and how to handle the visible unsubscribe link. - [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, complaint, and received-mail events pushed to your endpoint as signed HTTP callbacks, with automatic retries and dead-letter replay. - [Receiving email](https://mailfully.com/docs/guides/receiving-email.md): Receive mail at a verified domain or a hosted mailfully.app address, get an email.received webhook, and read the body, attachments, and raw MIME. - [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, construct the client, handle the { data, error } result tuple, and map every SDK method to its API endpoint. - [CLI](https://mailfully.com/docs/sdks/cli.md): Install the mailfully CLI, authenticate once, and send mail, verify domains, inspect the message log, and read analytics without leaving the terminal. - [MCP server](https://mailfully.com/docs/sdks/mcp.md): Connect Grok, Cursor, or Claude Code to the Mailfully MCP server to send email and check email status and domains with an API key. ## Deliverability and help - [Why emails go to spam](https://mailfully.com/docs/deliverability/why-emails-go-to-spam.md): Work through the four causes of inbox placement failure in order: authentication, list quality, content, and sending reputation. - [Gmail and Yahoo sender requirements](https://mailfully.com/docs/deliverability/gmail-and-yahoo-requirements.md): What bulk senders must do to keep reaching Gmail and Yahoo, which requirements Mailfully satisfies for you, and which are yours. - [Subdomain or root domain](https://mailfully.com/docs/deliverability/subdomain-or-root-domain.md): Why a sending subdomain is the safer default, what it isolates, and why verification never inherits from a parent domain. - [Warming up a new domain](https://mailfully.com/docs/deliverability/warming-up.md): Ramp volume on a new sending domain over the first weeks, and how the daily cap and account review interact with that ramp. - [IP pools](https://mailfully.com/docs/concepts/ip-pools.md): Which IPs your mail leaves from, how an account moves from the warm-up pool to the shared pool, and when a dedicated IP is worth buying. - [Why an address was suppressed](https://mailfully.com/docs/deliverability/suppression-causes.md): Trace a suppression entry back to the bounce, complaint, or manual add that created it, and decide whether removing it is safe. - [Troubleshooting](https://mailfully.com/docs/troubleshooting/overview.md): Find the right page from the symptom you can see or the error type you received, across domains, delivery, sending, receiving, and API keys. - [Domain will not verify](https://mailfully.com/docs/troubleshooting/domain-not-verifying.md): Read the per-record DKIM and MAIL FROM statuses, find the DNS record that is missing or wrong, and re-check or restart verification. - [MX record conflicts](https://mailfully.com/docs/troubleshooting/mx-record-conflicts.md): Fix a 409 mx_conflict when you turn on receiving, and see why the sending MX record cannot collide with your Google Workspace or Microsoft 365 records. - [Live sending is refused](https://mailfully.com/docs/troubleshooting/live-sending-refused.md): Nine refusals block a send because of your domain or your account. Match the error type to its cause, from an unverified domain to a past-due payment. - [Delivered but not received](https://mailfully.com/docs/troubleshooting/delivered-but-not-received.md): The send was accepted or shows delivered and nothing arrived. Check test mode, message status, suppression, spam and recipient routing in order. - [Received mail is missing](https://mailfully.com/docs/troubleshooting/received-mail-missing.md): Work out why a message sent to your domain or hosted address never appeared in Mailfully, or appears but cannot be opened. - [Adding a domain was refused](https://mailfully.com/docs/troubleshooting/domain-add-refused.md): Tell apart the ways a domain add is refused: a reserved or unownable domain, another org holding the parent, your plan's domain limit, a rate limit, and a conflict. - [Calling the API from a browser](https://mailfully.com/docs/troubleshooting/browser-requests.md): A browser fetch to the Mailfully API fails with a CORS error. Call Mailfully from your server instead of your frontend. - [A leaked API key](https://mailfully.com/docs/troubleshooting/leaked-api-key.md): Contain an exposed Mailfully key: rotate or revoke it from the dashboard, then audit what it could reach. - [Publishing your DNS records](https://mailfully.com/docs/dns/overview.md): The six records Mailfully asks you to publish, what each one does, the naming traps common to every DNS host, and how to verify with dig. - [Cloudflare DNS](https://mailfully.com/docs/dns/cloudflare.md): Add Mailfully's six sending records in Cloudflare, with the orange-cloud proxy switched off so the DKIM CNAMEs still resolve. - [GoDaddy DNS](https://mailfully.com/docs/dns/godaddy.md): GoDaddy treats the Name field as relative to your domain, which is what doubles the suffix on Mailfully's DKIM records. - [Namecheap DNS](https://mailfully.com/docs/dns/namecheap.md): Namecheap keeps everything on the Advanced DNS tab and adds one record type at a time. Here is that order for Mailfully. - [Route 53 DNS](https://mailfully.com/docs/dns/route53.md): Route 53 wants TXT values wrapped in quotes and MX priority inline in the value box. Publish Mailfully's records to match. - [Vercel DNS](https://mailfully.com/docs/dns/vercel.md): Vercel serves DNS only once your nameservers point at it, and then takes Mailfully's six records with no extra translation. - [Porkbun DNS](https://mailfully.com/docs/dns/porkbun.md): Porkbun labels the value column Answer and splits host from domain. Map Mailfully's DKIM, MAIL FROM, SPF, and DMARC onto it. ## 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 is saved and (unless every recipient is suppressed)… - [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. Sets up DKIM signing and a custom MAIL FROM subdomain, then returns the domain plus the exact DNS records to publish (3 DKIM… - [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 with its status and the DNS records to publish. - [Delete a domain](https://mailfully.com/docs/api-reference/domains/delete.md): Deletes a sending domain. On success it returns 204 No Content with an empty body. Any key with the send scope can delete, test or live. - [Verify a domain](https://mailfully.com/docs/api-reference/domains/verify.md): Re-checks DNS and returns the domain's current status (no DNS records). - [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. - [Update domain receiving](https://mailfully.com/docs/api-reference/domains/update-receiving.md): Turn receiving on or off for a domain. The body takes exactly one field, receiving; any other field, or none, is a 422. - [List received emails](https://mailfully.com/docs/api-reference/receiving/list.md): List the organization's received email, newest first. Rows carry metadata only; fetch one email for its body. Paging runs both ways. - [Retrieve a received email](https://mailfully.com/docs/api-reference/receiving/get.md): Retrieve one received email with its body, headers, receipt verdicts, attachment metadata, and a download link for the original MIME. - [List attachments](https://mailfully.com/docs/api-reference/receiving/list-attachments.md): List every attachment on one received email, in the order it was stored, each with a download link. - [Retrieve an attachment](https://mailfully.com/docs/api-reference/receiving/get-attachment.md): Retrieve one attachment on a received email, with a download link that lasts at most one hour (expires_at is exact). An unknown attachment id returns 404. - [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 signing_secret (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 signing_secret is never included. - [Retrieve a webhook endpoint](https://mailfully.com/docs/api-reference/webhooks/get.md): Retrieve one webhook endpoint by id (no signing_secret). Needs the manage:webhooks scope, which can be minted onto a live API key. - [Delete a webhook endpoint](https://mailfully.com/docs/api-reference/webhooks/delete.md): Delete a webhook endpoint. Needs the manage:webhooks scope, which can be minted onto a live 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): Resend a dead-lettered delivery to that endpoint as a new first attempt (the endpoint 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 lowercased and trimmed before it is stored; the format is not validated. - [Remove a suppression](https://mailfully.com/docs/api-reference/suppressions/delete.md): Removes a suppression. A 503 means nothing was removed; retry. Needs the manage:suppressions scope, which can be minted onto a live API key. - [Get daily analytics](https://mailfully.com/docs/api-reference/analytics/daily.md): Return exact per-day delivery counters over a date window. - [Get daily engagement events](https://mailfully.com/docs/api-reference/analytics/engagement.md): Return retained raw open and click event counts by UTC day, scoped to the credential's environment. - [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. - [List send refusals](https://mailfully.com/docs/api-reference/refusals/list.md): List the sends a quota or review limit refused, newest first. - [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, or one mid-rotation-grace with a future-dated revoked_at, is stamped revoked_at = now and rejected immediately…