Thank you for your message
We have received your email and will respond shortly.
", }); await message.reply( new EmailMessage(message.to, message.from, reply.asRaw()), ); // Also forward to human team await message.forward("team@example.com"); }, }; ``` ```ts import { EmailMessage } from "cloudflare:email"; import { createMimeMessage } from "mimetext"; export default { async email(message, env, ctx): PromiseSupport Request Received
Thank you for contacting support. Your request has been assigned ticket #${Date.now()}.
Expected response time: 2-4 hours during business hours.
`; } else if (recipient.includes("sales@")) { html = `Sales Inquiry Received
Thank you for your interest in our products.
A sales representative will contact you within 24 hours.
`; } else { html = `Message Received
Thank you for your message. We will respond within 2 business days.
`; } const reply = createMimeMessage(); if (messageId) { reply.setHeader("In-Reply-To", messageId); reply.setHeader("References", messageId); } reply.setSender(recipient); reply.setRecipient(sender); reply.setSubject(`Re: ${subject}`); reply.addMessage({ contentType: "text/plain", data: html.replace(/<[^>]*>/g, ""), }); reply.addMessage({ contentType: "text/html", data: html }); await message.reply(new EmailMessage(recipient, sender, reply.asRaw())); // Forward to appropriate team await message.forward("team@example.com"); }, }; ``` ### Reject emails Reject emails with a permanent SMTP error: ```ts export default { async email(message, env, ctx): PromiseWelcome!
Thanks for signing up.
", "text": "Welcome! Thanks for signing up." }' ``` For multiple recipients, CC/BCC, and named addresses, refer to [Specify recipients](https://developers.cloudflare.com/email-service/examples/email-sending/recipients/). ## Attachments Send files by including base64-encoded content in the `attachments` array. The total message size must not exceed **5 MiB** (including attachments). ```bash curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/email/sending/send" \ --header "Authorization: BearerInvoice attached
Please find your invoice attached.
", "attachments": [ { "content": "JVBERi0xLjQKJeLjz9MK...", "filename": "invoice-12345.pdf", "type": "application/pdf", "disposition": "attachment" } ] }' ``` For inline images and file uploads, refer to [Email attachments](https://developers.cloudflare.com/email-service/examples/email-sending/email-attachments/). ## Custom headers Set custom headers for threading, list management, or tracking. Refer to the [email headers reference](https://developers.cloudflare.com/email-service/reference/headers/) for the full list of allowed headers. ```bash curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/email/sending/send" \ --header "Authorization: BearerWeekly Digest
", "headers": { "List-Unsubscribe": "Welcome!
Thanks for signing up.
", text: "Welcome! Thanks for signing up.", }); ``` For multiple recipients, CC/BCC, and named addresses, refer to [Specify recipients](https://developers.cloudflare.com/email-service/examples/email-sending/recipients/). ### Attachments Send files by including base64-encoded content in the `attachments` array. The total message size must not exceed 5 MiB (including attachments). ```ts const response = await env.EMAIL.send({ to: "customer@example.com", from: "invoices@yourdomain.com", subject: "Your Invoice", html: "Invoice attached
Please find your invoice attached.
", attachments: [ { content: "JVBERi0xLjQKJeLjz9MKMSAwIG9iag...", // Base64 PDF content filename: "invoice-12345.pdf", type: "application/pdf", disposition: "attachment", }, ], }); ``` For inline images and file uploads, refer to [Email attachments](https://developers.cloudflare.com/email-service/examples/email-sending/email-attachments/). ## Error handling Handle email sending errors gracefully: ```ts export default { async fetch(request: Request, env: Env): PromiseHello from legacy API
", }); const message = new EmailMessage( "sender@yourdomain.com", "recipient@example.com", msg.asRaw(), ); await env.EMAIL.send(message); return new Response("Legacy email sent"); }, }; ``` --- ## Next steps - Refer to the [REST API](https://developers.cloudflare.com/email-service/api/send-emails/rest-api/) for sending emails without Workers - Refer to [SMTP](https://developers.cloudflare.com/email-service/api/send-emails/smtp/) for sending from any SMTP-capable application or mail client - Refer to [email sending examples](https://developers.cloudflare.com/email-service/examples/email-sending/) for common patterns - Refer to the [Email Routing API](https://developers.cloudflare.com/email-service/api/route-emails/) for handling incoming emails - Explore [email authentication](https://developers.cloudflare.com/email-service/concepts/email-authentication/) for better deliverability Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/api/send-emails/workers-api/#page","headline":"Email Sending Workers API","description":"Email Sending Workers API methods, types, binding, and errors.","url":"https://developers.cloudflare.com/email-service/api/send-emails/workers-api/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/api/send-emails/workers-api/og.png?v=84b629fb5504662d","dateModified":"2026-10-15","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Understand bounce handling and reputation management for optimal email delivery with Email Service. title: Email deliverability image: https://developers.cloudflare.com/email-service/concepts/deliverability/og.png?v=6445422fd87b5279 --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Email deliverability Understand bounce handling and reputation management for optimal email delivery. Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/concepts/deliverability/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) When you send an email, there is no guarantee it reaches the recipient's inbox. Inbox providers like Gmail, Yahoo, Outlook, and iCloud invest heavily in filtering out unwanted email. If you send poorly targeted emails, have high bounce rates, or trigger spam complaints, these providers may flag your domain as untrustworthy. Once that happens, even your legitimate emails can end up in spam or be blocked outright. This concept is referred to as email deliverability: maintaining a healthy sending reputation so that inbox providers trust your emails. Cloudflare Email Service helps with this by automatically handling bounces, managing suppression lists, and authenticating your emails through SPF, DKIM, and DMARC. ## Bounces Bounces occur when emails cannot be delivered to recipients. There are two types of bounces: **hard bounces** and **soft bounces**. ### Hard bounces Hard bounces are permanent delivery failures that occur when: - The recipient address does not exist. - The recipient domain does not exist. - The receiving server permanently rejects the recipient. **Hard bounces are never retried** because the failure is permanent. Emails that hard bounce will generate a bounce notification to the sender address and can be monitored through [analytics](https://developers.cloudflare.com/email-service/observability/metrics-analytics/). Email Service adds eligible recipient-side hard bounces to your [suppression list](https://developers.cloudflare.com/email-service/concepts/suppressions/). Suppressions have no expiration when the mailbox or domain does not exist. They also have no expiration when the recipient remains unavailable across repeated delivery attempts. Other eligible hard-bounce suppressions last seven days. ### Soft bounces Soft bounces are temporary failures that may succeed if retried: - Recipient mailbox is full - Email server temporarily down - Rate limiting or greylisting Cloudflare automatically retries soft bounces with exponential backoff. Eligible recipient-side failures create a 24-hour suppression. ## Reputation management Cloudflare automatically manages: - **IP reputation**: Managed sending infrastructure optimized for deliverability - **Domain authentication**: DKIM signing, SPF alignment, DMARC compliance - **Feedback processing**: ISP complaint handling and suppression list management ### Best practices #### Content and list hygiene Avoid content that can trigger spam-detection or can be perceived as unwanted content: - Avoid spam trigger words (FREE, URGENT, GUARANTEED) - Include both HTML and plain text versions - Use legitimate URLs and clear sender identification Ensure that your email lists are clean and contain intended recipients: - Validate emails before sending - Implement double opt-in for subscriptions - Remove hard bounced addresses immediately Ensure that your deliverability stays above key metrics to avoid affecting your email sending reputation: - Delivery rate >95% - Hard bounce rate < 2% - Complaint rate < 0.1% #### Use separate domains for separate purposes Each domain builds its own deliverability reputation with inbox providers. Use separate domains or subdomains for different types of email so that one category does not affect the reputation of another. For example: - `notifications.yourdomain.com` for transactional emails (order confirmations, password resets) - `marketing.yourdomain.com` for marketing and promotional emails - `yourdomain.com` for important account-related communications This way, if marketing emails generate higher complaint rates, your transactional email deliverability is not impacted. Each domain can be onboarded separately through [domain configuration](https://developers.cloudflare.com/email-service/configuration/domains/). Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/concepts/deliverability/#page","headline":"Email deliverability","description":"Understand bounce handling and reputation management for optimal email delivery with Email Service.","url":"https://developers.cloudflare.com/email-service/concepts/deliverability/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/concepts/deliverability/og.png?v=6445422fd87b5279","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: SPF, DKIM, and DMARC authentication for secure and deliverable email sending with Email Service. title: Email authentication image: https://developers.cloudflare.com/email-service/concepts/email-authentication/og.png?v=3c92dd4aa6787073 --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Email authentication Learn about SPF, DKIM, and DMARC for secure and deliverable email sending. Last updated Jun 9, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/concepts/email-authentication/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Email authentication verifies sender identity and improves deliverability. **Cloudflare Email Service handles authentication automatically**, but understanding these concepts helps troubleshoot issues. ## SPF (Sender Policy Framework) SPF ensures that no one else can send emails with your domain by authorizing which mail servers are allowed to send on your behalf. Email Service configures separate SPF records for sending and routing: - **Email Sending** SPF record on `cf-bounce.yourdomain.com`: ```txt TXT cf-bounce.yourdomain.com "v=spf1 include:_spf.mx.cloudflare.net ~all" ``` - **Email Routing** SPF record on the root domain: ```txt TXT yourdomain.com "v=spf1 include:_spf.mx.cloudflare.net ~all" ``` SPF works by: 1. Publishing authorized IP addresses in DNS 2. Recipient servers checking your SPF record 3. Comparing the sending IP against authorized IPs 4. Passing or failing based on the result ## DKIM (DomainKeys Identified Mail) DKIM ensures that emails have not been tampered during transit by cryptographically signing them with your domain's private key. **How DKIM works:** 1. Email headers and body are signed with a private key 2. DKIM-Signature header is added to the email 3. Public key is published in DNS 4. Recipients use the public key to verify the signature Email Service uses separate DKIM selectors for sending and routing: - **Email Sending**: `cf-bounce._domainkey.yourdomain.com` - **Email Routing**: `cf2024-1._domainkey.yourdomain.com` Cloudflare automatically generates and manages DKIM keys. You add the provided DNS records from the dashboard. ## DMARC (Domain-based Message Authentication, Reporting & Conformance) DMARC ensures that emails claiming to be from your domain actually pass SPF and DKIM checks, telling recipients what to do with emails that fail authentication. **DMARC record example:** ```txt TXT _dmarc.yourdomain.com "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com" ``` Note If the `rua` mailto address is on a different domain than the DMARC record (common when using a DMARC aggregator), the receiving domain must publish a `_report._dmarc.yourdomain.com` TXT record to authorize reports. Refer to [RFC 7489 §7.1 ↗︎](https://datatracker.ietf.org/doc/html/rfc7489#section-7.1). **DMARC policies:** - `p=none` - Monitor only (recommended to start) - `p=quarantine` - Quarantine suspicious emails - `p=reject` - Reject unauthenticated emails **Deployment strategy:** 1. Start with `p=none` to monitor authentication 2. Gradually increase to `p=quarantine` 3. Finally implement `p=reject` after confirming legitimate mail authenticates ## Key benefits Email authentication provides: - **Deliverability**: Improves inbox placement - **Security**: Protects your domain from spoofing - **Reputation**: Maintains good sender reputation with ISPs Cloudflare Email Service handles authentication automatically, but you need to configure the DNS records for SPF, DKIM, and DMARC as provided in your dashboard. Email Sending and Email Routing use separate DNS records -- refer to [Domain configuration](https://developers.cloudflare.com/email-service/configuration/domains/) for the full details. Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/concepts/email-authentication/#page","headline":"Email authentication","description":"SPF, DKIM, and DMARC authentication for secure and deliverable email sending with Email Service.","url":"https://developers.cloudflare.com/email-service/concepts/email-authentication/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/concepts/email-authentication/og.png?v=3c92dd4aa6787073","dateModified":"2026-06-09","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: The complete email processing flow from send request to final delivery status in Email Service. title: Email lifecycle image: https://developers.cloudflare.com/email-service/concepts/email-lifecycle/og.png?v=b525893164e18a0f --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Email lifecycle Understand the complete email processing lifecycle from request received through final delivery status with Cloudflare Email Service Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/concepts/email-lifecycle/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) The email lifecycle describes the complete journey of an email through Cloudflare Email Service. Understanding this process helps you optimize your email implementation and troubleshoot delivery issues. Email Sending and Email Routing follow distinct processing pipelines. The outbound flow covers emails you send through the service; the inbound flow covers emails received on domains configured with Email Routing. ## Outbound flow (Email Sending) Every email sent through Cloudflare Email Service follows this processing pipeline: ``` flowchart LR A[Request Received] --> B["Rate Limit, Authentication & Suppression Check"] --> E[Delivery Attempt] E --> G{Success?} G -->|Yes, successfully delivered| F[Final Status & Metrics] G -->|No - Soft Bounce| H[Retry with Exponential Backoff] G -->|No - Hard Bounce| F H -->|Retries remaining| E H -->|Max retries exceeded| F ``` ### Stage details 1. **Request received:** The system validates the email format, sender authorization, and message structure. Invalid requests are rejected immediately and do not proceed to the next stage. 2. **Rate limit check:** The system checks sending [limits](https://developers.cloudflare.com/email-service/platform/limits/) per account, domain, and recipient to prevent abuse. Requests that exceed these limits are temporarily rejected and must be retried later. 3. **Authentication and reputation**: The system performs email authentication checks and evaluates sender reputation: - **SPF (Sender Policy Framework)**: Verifies that the sending IP address is authorized to send emails for the domain by checking DNS TXT records. This prevents domain spoofing and improves deliverability. - **DKIM (DomainKeys Identified Mail)**: Validates the email's cryptographic signature to ensure message integrity and authenticate the sender domain. This builds trust with recipient servers. - **DMARC (Domain-based Message Authentication)**: Applies domain owner policies for handling emails that fail SPF or DKIM checks, helping prevent phishing and brand impersonation while providing feedback reports. These authentication mechanisms work together to establish sender legitimacy and protect against email fraud. Senders with low reputation scores may experience throttling or delayed processing. 4. **Suppression list check:** The system checks each recipient against the Email Sending [suppression list](https://developers.cloudflare.com/email-service/concepts/suppressions/) for your account. Suppressed recipients do not reach the delivery stage or count toward your quota. The per-sending-domain [**Drop suppressed recipients** setting](https://developers.cloudflare.com/email-service/configuration/domains/#drop-suppressed-recipients) is off by default. When off, the REST API returns `400`, the Workers binding throws `E_RECIPIENT_SUPPRESSED`, and SMTP rejects the message if any recipient is suppressed. When on, Email Service removes suppressed recipients and processes the remaining recipients. Email Service does not process unsubscribe links, so add unsubscribed recipients manually. 5. **Delivery attempt:** The system connects to the recipient's mail server and attempts message delivery via SMTP. When delivery fails, the system applies different retry logic based on the failure type: - **Soft bounces (4xx responses)**: The system retries delivery using exponential backoff timing - **Hard bounces (5xx responses)**: The system marks the email as permanently failed with no retry attempts 6. **Server response handling:** The system processes SMTP response codes from the recipient server to determine the final email status: - **2xx codes**: The email was delivered successfully - **4xx codes**: Temporary failure occurred and the email will be retried - **5xx codes**: Permanent failure occurred and the email cannot be delivered 7. **Final status and metrics:** Based on the server response, the system assigns emails one of these final statuses: - **Delivered**: The email was successfully accepted by the recipient server - **Delivery failed**: The email permanently failed delivery (hard bounce) or exceeded the maximum retry attempts (soft bounce). This status appears as `deliveryFailed` when querying the [GraphQL Analytics API](https://developers.cloudflare.com/email-service/observability/metrics-analytics/). ## Inbound flow (Email Routing) Every email received on a domain configured with Email Routing follows this processing pipeline: ``` flowchart LR A[SMTP Receipt] --> B[Authentication Check] B --> C{Authenticated?} C -->|Yes| D[Rule Match] C -->|No| R[Reject] D --> E{Action?} E -->|Send to email| F[ARC Sign & SRS Rewrite] E -->|Send to Worker| W[Worker] E -->|Drop| X[Drop] W --> Y{Worker action?} Y -->|forward| F Y -->|reply| F Y -->|setReject| R F --> G[Outbound Delivery] G --> H[Final Status & Metrics] ``` ### Stage details 1. **SMTP receipt:** A sending server connects to a Cloudflare MX server and submits the message over SMTP. Messages larger than the [inbound message size limit](https://developers.cloudflare.com/email-service/platform/limits/) are rejected at this stage. 2. **Authentication check:** The system performs [SPF, DKIM, DMARC, and ARC](https://developers.cloudflare.com/email-service/concepts/email-authentication/) checks on the incoming message. Mail that fails authentication according to the sender's DMARC policy is rejected. Mail from IP addresses on a Realtime Block List is also rejected at this stage. Refer to [Postmaster information](https://developers.cloudflare.com/email-service/reference/postmaster/) for details. 3. **Rule match:** The system matches the recipient address against your configured [routing rules](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/). If [subaddressing](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/#subaddressing) is enabled, sub-addressed recipients fall back to the base routing rule. If no rule matches and the [catch-all rule](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/#catch-all-rule) is enabled, the catch-all rule applies. 4. **Action:** The system applies the matched rule's action: - **Send to an email**: The message is forwarded to the verified destination address (stage 5). - **Send to a Worker**: The message is passed to your [Worker](https://developers.cloudflare.com/email-service/api/route-emails/email-handler/). The Worker can call `forward()`, `reply()`, or `setReject()`. - **Drop**: The message is silently discarded. No further processing occurs. 5. **ARC sign and SRS rewrite:** For forwarded messages, the system adds an ARC seal preserving the original authentication results and rewrites the envelope sender using the [Sender Rewriting Scheme](https://developers.cloudflare.com/email-service/reference/postmaster/#sender-rewriting). This allows SPF to pass at the destination server. 6. **Outbound delivery:** The system connects to the destination mail server and delivers the message. Soft bounces are retried with exponential backoff. Hard bounces are returned to the original sender in-session as upstream SMTP errors. Refer to [Postmaster: SMTP errors](https://developers.cloudflare.com/email-service/reference/postmaster/#smtp-errors). 7. **Final status and metrics:** The final outcome is recorded and available through the [Activity log](https://developers.cloudflare.com/email-service/observability/logs/) and the [GraphQL Analytics API](https://developers.cloudflare.com/email-service/observability/metrics-analytics/). Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/concepts/email-lifecycle/#page","headline":"Email lifecycle","description":"The complete email processing flow from send request to final delivery status in Email Service.","url":"https://developers.cloudflare.com/email-service/concepts/email-lifecycle/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/concepts/email-lifecycle/og.png?v=b525893164e18a0f","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Understand suppression scope, triggers, expiration, and enforcement. title: Suppression lists image: https://developers.cloudflare.com/email-service/concepts/suppressions/og.png?v=b7a3832c3a6526eb --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Suppression lists Suppression lists prevent Email Service from sending to recipients who should not receive mail. Cloudflare adds entries after eligible bounces and spam complaints. You can also add entries manually. Last updated Sep 25, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/concepts/suppressions/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) An Email Sending suppression list contains recipients that Email Service does not contact. Suppressions protect your sender reputation and help prevent sending unwanted mail. Cloudflare creates suppressions after eligible delivery failures and spam complaints. You can also add entries for recipients who should not receive mail. To add or remove entries, refer to [Manage suppressions](https://developers.cloudflare.com/email-service/configuration/suppressions/). Suppressions only apply to Email Sending. ## Suppression scope Each suppression has a scope. The scope controls which sending domains the suppression applies to: | Scope | Applies to | | --- | --- | | `account` | Every sending domain and subdomain in your account | | `sending_domain` | One sending domain, such as `mail.myappexample.com` | The sending domain of a message is the domain of its sender address. This is the `from` address for the [REST API](https://developers.cloudflare.com/email-service/api/send-emails/rest-api/) and [Workers binding](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/), and the envelope `MAIL FROM` address for [SMTP](https://developers.cloudflare.com/email-service/api/send-emails/smtp/). A `sending_domain` suppression matches only its exact domain. A suppression for `myappexample.com` does not block mail from `mail.myappexample.com`, and a suppression for `mail.myappexample.com` does not block mail from `myappexample.com`. Email Service suppresses a recipient if the address has an `account` suppression, or a `sending_domain` suppression for the sending domain of the message. Bounce and complaint suppressions use the `sending_domain` scope, with the sending domain of the message that bounced or received the complaint. A complaint creates an `account` suppression when Cloudflare cannot identify the sending domain of the original message. ## Suppression rules The following table describes automatic and manual creation rules and expiration: | Reason | Created when | Expiration | | --- | --- | --- | | Manual (`manual`) | You add the recipient through the dashboard or API | The time you choose, or no expiration | | Spam complaint (`complaint`) | Cloudflare receives and validates a complaint from the recipient's email provider | No expiration | | Hard bounce (`hard_bounce`) | Any other eligible recipient-side permanent rejection occurs | 7 days | | Hard bounce (`hard_bounce`) | The recipient mailbox or domain does not exist, or a recipient-side issue persists across repeated delivery attempts | No expiration | | Soft bounce (`soft_bounce`) | An eligible recipient-side temporary failure occurs, such as a full mailbox or rate limit | 24 hours by default | The [account Email Sending suppression management REST API](https://developers.cloudflare.com/api/resources/email_sending/subresources/suppressions/) can return Cloudflare-managed entries with a `policy` reason. Clients must use `read_only` to determine mutability, not infer it from `reason`. You cannot update or delete an entry when `read_only` is `true`. To investigate one, [contact Cloudflare Support](https://developers.cloudflare.com/support/contacting-cloudflare-support/). ### Manual suppressions Manual suppressions allow you to add application-level decisions that Email Service cannot observe. For example, if a user manually unsubscribes from emails in your app, you can add their email to your Email Service suppression list. You select the expiration when creating the entry. An entry without an expiration remains active until you delete it. You also select the scope. Manual suppressions use the `account` scope by default. Email Service does not check that your account sends from a `sending_domain` value. A suppression for a domain that you do not send from never blocks mail. ### Spam complaints Email providers send feedback reports when recipients mark messages as spam. Cloudflare validates these reports before creating complaint suppressions. Complaint suppressions are created without an expiration. You can change or delete one when `read_only` is `false`. We recommend changing or deleting one only after the recipient opts in again through your application. ### Hard bounces A hard bounce is a permanent rejection of one delivery attempt. Some addresses become valid again after their owner fixes the mailbox or domain. Email Service creates a suppression without an expiration when the mailbox or domain does not exist. It also does this when a recipient-side issue persists across repeated delivery attempts without a successful delivery. Other eligible hard-bounce suppressions last seven days. ### Soft bounces A soft bounce is a temporary recipient-side failure. Examples include a full mailbox, a temporarily unavailable server, or recipient-side rate limiting. Eligible soft-bounce suppressions last 24 hours by default. Email Service resumes sending after the suppression expires. Not every temporary delivery failure creates a suppression. For example, Email Service does not suppress a recipient for a sender-side authentication or reputation problem. ## Enforcement by sending method Each sending domain has a [**Drop suppressed recipients** setting](https://developers.cloudflare.com/email-service/configuration/domains/#drop-suppressed-recipients). The setting is off by default. | Sending method | Setting off | Setting on | | --- | --- | --- | | [REST API](https://developers.cloudflare.com/email-service/api/send-emails/rest-api/) | Returns `400` and rejects the request when any recipient is suppressed. | Removes suppressed recipients and processes the remaining recipients. | | [Workers binding](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/) | Throws `E_RECIPIENT_SUPPRESSED` and rejects the `send()` call when any recipient is suppressed. | Removes suppressed recipients and processes the remaining recipients. | | [SMTP](https://developers.cloudflare.com/email-service/api/send-emails/smtp/) | Rejects the message when any recipient is suppressed. | Removes suppressed recipients and processes the remaining recipients. If none remain, SMTP may return `250 2.0.0 Ok` without a Message-ID and delivers nothing. | Suppressed recipients do not count toward your [monthly quota](https://developers.cloudflare.com/email-service/platform/pricing/) or daily sending limits. They appear as **Rejected** in [Email sending logs](https://developers.cloudflare.com/email-service/observability/logs/). ## Best practices - Add manual suppressions for unsubscribes. - Use the `account` scope when a recipient must not receive mail from any of your domains. Use the `sending_domain` scope when the decision applies to one subdomain only. - Require recipients to opt in again through your application. - Verify addresses before deleting suppressions. - Investigate patterns across repeated bounces. - Let temporary suppressions expire automatically. ## Related resources - Use [Manage suppressions](https://developers.cloudflare.com/email-service/configuration/suppressions/) to manage entries through the dashboard or API. - Review [Email deliverability](https://developers.cloudflare.com/email-service/concepts/deliverability/) to understand bounce and complaint effects. - Follow [Email lifecycle](https://developers.cloudflare.com/email-service/concepts/email-lifecycle/) to locate suppression checks in the sending flow. - Review [Suppression list limits](https://developers.cloudflare.com/email-service/platform/limits/#suppression-list-limits) for API limits. - Use [Email sending logs](https://developers.cloudflare.com/email-service/observability/logs/) to investigate rejected sends. Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/concepts/suppressions/#page","headline":"Suppression lists","description":"Understand suppression scope, triggers, expiration, and enforcement.","url":"https://developers.cloudflare.com/email-service/concepts/suppressions/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/concepts/suppressions/og.png?v=b7a3832c3a6526eb","dateModified":"2026-09-25","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Configure and verify DNS records for Email Service sending and routing on your domain. title: Domain configuration image: https://developers.cloudflare.com/email-service/configuration/domains/og.png?v=4871d876f74d072f --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Domain configuration Configure domains for Cloudflare Email Service, manage DNS records, and verify domain setup for both email sending and routing. Last updated Oct 15, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/configuration/domains/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Configure your domains to work with Cloudflare Email Service. This includes DNS record management, domain verification, and advanced domain settings. ## Automatic DNS configuration Cloudflare can configure all required DNS records for you when you onboard a domain onto Email Sending or Email Routing. Before using Email Sending, configure your domain. 1. In the Cloudflare dashboard, go to **Compute** > **Email Service** > **Email Sending**. [Go to **Email Sending** ↗](https://dash.cloudflare.com/?to=/:account/email-service/sending) 2. Select **Onboard Domain**. 3. Choose a domain from your Cloudflare account. Optionally review the DNS records that Cloudflare will add to the `cf-bounce` subdomain of your domain: - MX records to route bounce emails to Cloudflare. - TXT record for SPF to authorize sending emails. - TXT record for DKIM to provide authentication for emails sent from your domain. - TXT record for DMARC on `_dmarc.yourdomain.com`. 4. Select **Done**. Note DNS changes can take up to 24 hours to propagate globally, but usually complete within 5-15 minutes for domains using Cloudflare DNS. Once your domain is onboarded, you can start sending emails. Before using Email Routing, configure your domain. 1. In the Cloudflare dashboard, go to **Compute** > **Email Service** > **Email Routing**. [Go to **Email Routing** ↗](https://dash.cloudflare.com/?to=/:account/email-service/routing) 2. Select **Onboard Domain**. 3. Choose a domain from your Cloudflare account. Optionally review the DNS records that Cloudflare will add to your root domain: - MX records to route incoming emails to Cloudflare. - TXT record for SPF to authorize email routing. - TXT record for DKIM to provide authentication for routed emails. 4. Select **Done**. Note DNS changes can take up to 24 hours to propagate globally, but usually complete within 5-15 minutes for domains using Cloudflare DNS. Once your domain is onboarded, you can start routing emails. ## DNS record configuration details Cloudflare automatically configures required DNS records for both email sending and routing when you onboard a domain onto Email Service. Here are the specific details of the DNS records configured: ### Sending records These records authenticate your outbound emails. Email Sending creates DNS records on a `cf-bounce.` subdomain of your domain to handle bounce processing. These are separate from the records used by Email Routing. **Purpose**: Route bounce emails back to Cloudflare for processing. ```txt MX cf-bounce.yourdomain.com route1.mx.cloudflare.net MX cf-bounce.yourdomain.com route2.mx.cloudflare.net MX cf-bounce.yourdomain.com route3.mx.cloudflare.net ``` **Configuration:** - **Type**: MX - **Name**: `cf-bounce` (subdomain) - **Mail server**: Cloudflare MX servers - **Priority**: Assigned automatically by Cloudflare **Purpose**: Authorizes Cloudflare to send emails on behalf of your domain. ```txt TXT cf-bounce.yourdomain.com "v=spf1 include:_spf.mx.cloudflare.net ~all" ``` **Configuration:** - **Type**: TXT - **Name**: `cf-bounce` (subdomain) - **Value**: `v=spf1 include:_spf.mx.cloudflare.net ~all` - **TTL**: Auto **Purpose**: Provides cryptographic authentication for your emails. ```txt TXT cf-bounce._domainkey.yourdomain.com "v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..." ``` **Configuration:** - **Type**: TXT - **Name**: `cf-bounce._domainkey` (selector managed by Cloudflare) - **Value**: DKIM public key (provided by Cloudflare) - **TTL**: Auto **Purpose**: Sets policy for email authentication failures. ```txt TXT _dmarc.yourdomain.com "v=DMARC1; p=reject;" ``` **Configuration:** - **Type**: TXT - **Name**: `_dmarc` - **Value**: DMARC policy - **TTL**: Auto **Policy options:** - `p=none` - Monitor only (recommended for new setups) - `p=quarantine` - Quarantine suspicious emails - `p=reject` - Reject unauthenticated emails ### Routing records These records route incoming emails to Cloudflare and authenticate forwarded emails. Email Routing DNS records are configured on the root domain. **Purpose**: Route incoming emails to Cloudflare's mail servers. ```txt MX yourdomain.com route1.mx.cloudflare.net MX yourdomain.com route2.mx.cloudflare.net MX yourdomain.com route3.mx.cloudflare.net ``` **Configuration:** - **Type**: MX - **Name**: `@` (root domain) - **Mail server**: Cloudflare routing MX servers - **Priority**: Assigned automatically by Cloudflare **Purpose**: Authorizes Cloudflare to forward emails on behalf of your domain. ```txt TXT yourdomain.com "v=spf1 include:_spf.mx.cloudflare.net ~all" ``` **Configuration:** - **Type**: TXT - **Name**: `@` (root domain) - **Value**: `v=spf1 include:_spf.mx.cloudflare.net ~all` - **TTL**: Auto Existing SPF records If you have existing SPF records, merge them: `v=spf1 include:_spf.mx.cloudflare.net include:_spf.google.com ~all`. SPF records are limited to 10 DNS lookups total. If merging pushes you over the limit, consider flattening the record or removing non-essential `include:` entries. **Purpose**: Provides cryptographic authentication for forwarded emails. ```txt TXT cf2024-1._domainkey.yourdomain.com "v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..." ``` **Configuration:** - **Type**: TXT - **Name**: `cf2024-1._domainkey` (selector provided by Cloudflare) - **Value**: DKIM public key (provided by Cloudflare) - **TTL**: Auto **Separate from sending DKIM** - Email Routing uses its own DKIM selector (`cf2024-1._domainkey`) and keys, distinct from the sending DKIM selector (`cf-bounce._domainkey`). ## Domain verification Email Sending and Email Routing have separate DNS records and separate settings pages where you can verify their status. ### Verify Email Sending records 1. Go to **Compute** > **Email Service** > **Email Sending** > **Settings**. 2. The **DNS records** section shows all sending-related records: - **MX records** on `cf-bounce.yourdomain.com` - **SPF record** on `cf-bounce.yourdomain.com` - **DKIM record** on `cf-bounce._domainkey.yourdomain.com` - **DMARC record** on `_dmarc.yourdomain.com` 3. Each record shows either a **Locked** or **Unlocked** status. Both states indicate the record is configured correctly; the status reflects whether Email Service is managing the record. Refer to [Locked DNS records](#locked-dns-records) for more information. ### Verify Email Routing records 1. Go to **Compute** > **Email Service** > **Email Routing** > **Settings**. 2. The **DNS records** section shows all routing-related records: - **MX records** on `yourdomain.com` - **SPF record** on `yourdomain.com` - **DKIM record** on `cf2024-1._domainkey.yourdomain.com` 3. Each record shows either a **Locked** or **Unlocked** status. Both states indicate the record is configured correctly; the status reflects whether Email Service is managing the record. Refer to [Locked DNS records](#locked-dns-records) for more information. ### If records are not configured - Wait 5-15 minutes for DNS propagation. - Check DNS configuration in your domain's **DNS** > **Records** settings. ### Locked DNS records When Email Service onboarding succeeds, the DNS records it manages are locked to prevent accidental changes that would break mail flow. Locked records show a **Locked** status in the dashboard and cannot be edited or deleted from **DNS** > **Records** until they are unlocked. Only Email Routing records on the root domain (MX, SPF, and DKIM) support unlocking. Email Sending records on the `cf-bounce` subdomain stay managed by Email Service for the lifetime of the domain configuration. To unlock an Email Routing record: 1. Go to **Compute** > **Email Service** > **Email Routing**. [Go to **Email Routing** ↗](https://dash.cloudflare.com/?to=/:account/email-service/routing) 2. Select the domain, then open **Settings**. 3. Locate the record in the **DNS records** section and select **Unlock**. If you want to migrate to a different email provider without immediately interrupting service, unlock the routing records first, add the new provider's records alongside them, then remove the Email Service records once the new setup is verified. ### `_dc-mx` DNS responses This section applies only if your MX records point to hostnames that are proxied through Cloudflare. When an MX record on your domain points to a hostname that is proxied through Cloudflare, mail delivery to that hostname would normally fail because the Cloudflare proxy does not handle SMTP. To avoid this, Cloudflare automatically inserts a `_dc-mx.Support Ticket Created
Your support request has been received and assigned ticket number: ${ticketId}
We will respond within 2-4 hours during business hours.
Original subject: ${message.headers.get("subject")}
`, }); await message.reply( new EmailMessage(message.to, message.from, reply.asRaw()), ); // Forward to support team await message.forward("support-team@example.com"); } ``` ## Queue-based processing Process emails asynchronously using Cloudflare Queues. The `email()` handler sends a threaded acknowledgement with `message.reply()` and enqueues the message for later processing. The queue consumer runs in a separate invocation where the original `EmailMessage` is no longer available, so any follow-up emails it sends use `env.EMAIL.send()` instead. ```typescript import { EmailMessage } from "cloudflare:email"; import { createMimeMessage } from "mimetext"; interface Env { EMAIL: SendEmail; EMAIL_QUEUE: Queue; EMAIL_STORAGE: KVNamespace; EMAIL_ANALYTICS: AnalyticsEngine; SUPPORT_TICKETS?: KVNamespace; SALES_LEADS?: KVNamespace; } interface EmailQueueMessage { emailId: string; from: string; to: string; subject: string; timestamp: string; priority: "low" | "normal" | "high" | "urgent"; category: string; } export default { // Handle incoming emails async email(message, env, ctx): PromiseSupport Ticket Created
Your support request has been received and assigned ticket number: ${ticketId}
Priority: ${emailData.priority}
We will respond based on the priority level:
- Urgent: Within 1 hour
- High: Within 4 hours
- Normal: Within 24 hours
Original subject: ${emailData.subject}
`, }); return { ticketId, action: "ticket_created" }; } async function processSales( emailData: EmailQueueMessage, emailContent: any, env: Env, ) { // Create sales lead const leadId = `LEAD-${Date.now()}`; const leadData = { id: leadId, emailId: emailData.emailId, contact: emailData.from, subject: emailData.subject, priority: emailData.priority, status: "new", source: "email", createdAt: new Date().toISOString(), }; await env.SALES_LEADS?.put(leadId, JSON.stringify(leadData)); // Send sales response await env.EMAIL.send({ to: emailData.from, from: "sales@yourdomain.com", subject: `Re: ${emailData.subject}`, html: `Thank you for your interest!
We've received your sales inquiry and assigned it reference: ${leadId}
A member of our sales team will contact you within 24 hours.
Best regards,
Sales Team
Billing Inquiry Received
Thank you for contacting our billing department.
Your inquiry has been forwarded to our billing specialists who will respond within 2 business hours.
For immediate assistance, please call: +1-800-555-0123
`, }); return { action: "billing_forwarded" }; } async function processGeneral( emailData: EmailQueueMessage, emailContent: any, env: Env, ) { // Handle general inquiries await env.EMAIL.send({ to: emailData.from, from: "info@yourdomain.com", subject: `Re: ${emailData.subject}`, text: ` Thank you for contacting us. We have received your message and will respond within 48 hours. For urgent matters, please contact our support team at support@yourdomain.com. Best regards, Customer Service Team `, }); return { action: "general_acknowledged" }; } ``` ## Next steps - [Email handler](https://developers.cloudflare.com/email-service/api/route-emails/email-handler/) — reference for the `email()` handler and its actions. - [Spam filtering](https://developers.cloudflare.com/email-service/examples/email-routing/spam-filtering/) — block spam before storing or processing. - [Hard bounce handling](https://developers.cloudflare.com/email-service/examples/email-routing/hard-bounce-handling/) — detect and process bounce notifications. Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/examples/email-routing/email-storage/#page","headline":"Email storage and processing","description":"Store incoming emails in KV and process them with Queues for support tickets and workflow automation in Email Service.","url":"https://developers.cloudflare.com/email-service/examples/email-routing/email-storage/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/examples/email-routing/email-storage/og.png?v=0445d82bbad6b2f0","dateModified":"2026-06-09","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Detect hard bounce notifications and store recipients in Workers KV. title: Hard bounce handling image: https://developers.cloudflare.com/email-service/examples/email-routing/hard-bounce-handling/og.png?v=f99a6c6d7fdb1fa0 --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Hard bounce handling Detect and handle hard bounce emails to maintain sender reputation and manage undeliverable addresses Last updated Oct 15, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/examples/email-routing/hard-bounce-handling/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) This example detects hard bounce notifications and stores recipient addresses in Workers KV. ## Identify hard bounces Hard bounces occur when an email cannot be delivered due to permanent reasons: - Invalid email address: The email address does not exist - Domain does not exist: The domain name is invalid or expired - Mailbox full: The recipient's mailbox has exceeded storage limits - Email blocked: The recipient's server permanently rejects emails ## Configure bindings Configure your worker to handle bounce notifications: ```jsonc { "name": "bounce-handler", // Set this to today's date "compatibility_date": "2026-10-18", "send_email": [{ "name": "EMAIL" }], "kv_namespaces": [ { "binding": "SUPPRESSION_LIST", "id": "your-kv-namespace-id", }, ], } ``` ```toml name = "bounce-handler" # Set this to today's date compatibility_date = "2026-10-18" [[send_email]] name = "EMAIL" [[kv_namespaces]] binding = "SUPPRESSION_LIST" id = "your-kv-namespace-id" ``` ## Detect hard bounces ```javascript import * as PostalMime from "postal-mime"; export default { async email(message, env, ctx) { // Parse the raw email message const parser = new PostalMime.default(); const rawEmail = new Response(message.raw); const email = await parser.parse(await rawEmail.arrayBuffer()); // Check if this is a bounce notification if (isBounceNotification(email)) { const bounceInfo = await parseBounceInfo(email); if (bounceInfo.type === "hard") { await handleHardBounce(bounceInfo, env); console.log( `Hard bounce processed for: ${bounceInfo.originalRecipient}`, ); return; } } // Forward non-bounce emails normally await message.forward("admin@yourdomain.com"); }, }; function isBounceNotification(email) { // Check common bounce indicators const subject = email.subject?.toLowerCase() || ""; const fromAddress = email.from?.address?.toLowerCase() || ""; // Common bounce indicators const bounceSubjects = [ "mail delivery failed", "undelivered mail returned to sender", "delivery status notification", "returned mail", "mail system error", ]; const bounceFromPatterns = [ "mailer-daemon", "mail-daemon", "postmaster", "noreply", "bounce", ]; return ( bounceSubjects.some((phrase) => subject.includes(phrase)) || bounceFromPatterns.some((pattern) => fromAddress.includes(pattern)) ); } async function parseBounceInfo(email) { const text = email.text || ""; const html = email.html || ""; const content = text + " " + html; // Extract original recipient email const recipientMatch = content.match(/(?:to|for|recipient):\s*([^\s<]+@[^\s>]+)/i) || content.match(/([^\s<]+@[^\s>]+)/); const originalRecipient = recipientMatch ? recipientMatch[1] : null; // Determine bounce type based on content const hardBounceIndicators = [ "user unknown", "no such user", "invalid recipient", "recipient address rejected", "mailbox unavailable", "domain not found", "5.1.1", // SMTP error code for bad destination mailbox "5.1.2", // SMTP error code for bad destination system "5.4.1", // SMTP error code for no answer from host ]; const isHardBounce = hardBounceIndicators.some((indicator) => content.toLowerCase().includes(indicator.toLowerCase()), ); return { type: isHardBounce ? "hard" : "soft", originalRecipient, reason: extractBounceReason(content), timestamp: new Date().toISOString(), }; } function extractBounceReason(content) { // Extract the specific error message const reasonPatterns = [ /diagnostic[- ]code:\s*(.+)/i, /reason:\s*(.+)/i, /error:\s*(.+)/i, /(5\.\d+\.\d+[^.\n]*)/i, ]; for (const pattern of reasonPatterns) { const match = content.match(pattern); if (match) { return match[1].trim().split("\n")[0]; // Take first line only } } return "Unknown bounce reason"; } async function handleHardBounce(bounceInfo, env) { if (!bounceInfo.originalRecipient) { console.log("Could not extract original recipient from bounce"); return; } // Add to suppression list in KV await env.SUPPRESSION_LIST.put( bounceInfo.originalRecipient, JSON.stringify({ type: "hard_bounce", reason: bounceInfo.reason, timestamp: bounceInfo.timestamp, status: "suppressed", }), { metadata: { bounceType: "hard", addedDate: bounceInfo.timestamp, }, }, ); console.log( `Added ${bounceInfo.originalRecipient} to suppression list: ${bounceInfo.reason}`, ); } ``` ## Test the handler Create a test bounce notification: ```bash curl --request POST 'http://localhost:8787/cdn-cgi/local/email' \ --url-query 'from=mailer-daemon@example.com' \ --url-query 'to=bounce-handler@yourdomain.com' \ --header 'Content-Type: application/json' \ --data-raw 'From: Mail Delivery SubsystemInvoice #${invoiceData.number}
Dear ${invoiceData.customerName},
Invoice Details
Invoice Number: ${invoiceData.number}
Date: ${new Date(invoiceData.date).toLocaleDateString()}
Amount Due: $${invoiceData.total}
Due Date: ${new Date(invoiceData.dueDate).toLocaleDateString()}
Please find your invoice attached. Payment is due within 30 days.
Thank you for your business!
${reportData.title}
Period: ${reportData.period}
Key Metrics
Revenue: $${reportData.metrics.revenue.toLocaleString()}
New Users: ${reportData.metrics.users.toLocaleString()}
Growth Rate: ${reportData.metrics.growth}%
Performance Chart
For detailed analysis, please contact our team.
File Shared
${senderName} has shared a file with you.
${message ? `"${message}"
` : ""}File Details
Filename: ${file.name}
Size: ${formatFileSize(file.size)}
Type: ${getFileTypeDescription(file.type)}
The file is attached to this email for download.
Security notice: Always verify the source before opening attachments.
Login to your account
Click the link below to log in:
`, text: ` Login to your account Click this link to log in: ${magicUrl} `, }); return new Response( JSON.stringify({ success: true, message: "Magic link sent to your email", }), ); } function isValidEmail(email: string): boolean { return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); } ``` ## Next steps - [User signup flow](https://developers.cloudflare.com/email-service/examples/email-sending/signup-flow/) — combine magic links with account verification. - [Send method](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/) — full reference for the `send()` method. - [Email headers](https://developers.cloudflare.com/email-service/reference/headers/) — add tracking or list-management headers. Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/examples/email-sending/magic-link/#page","headline":"Email a login link","description":"Generate and email a login link from a Worker.","url":"https://developers.cloudflare.com/email-service/examples/email-sending/magic-link/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/examples/email-sending/magic-link/og.png?v=a014a614113a81d9","dateModified":"2026-10-15","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Send to multiple recipients, CC and BCC, and named addresses using the Workers binding, REST API, or SMTP. title: Specify recipients image: https://developers.cloudflare.com/email-service/examples/email-sending/recipients/og.png?v=350ae4cc036927b2 --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Specify recipients Specify multiple recipients, CC and BCC, and named addresses when sending with Email Service. Last updated Jun 9, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/examples/email-sending/recipients/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Email Service lets you specify recipients in several ways — multiple recipients, CC and BCC, and named addresses — using the [Workers binding](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/), the [REST API](https://developers.cloudflare.com/email-service/api/send-emails/rest-api/), or [SMTP](https://developers.cloudflare.com/email-service/api/send-emails/smtp/). The combined number of addresses across `to`, `cc`, and `bcc` must not exceed 50. See [Limits](https://developers.cloudflare.com/email-service/platform/limits/). ## Multiple recipients ```ts const response = await env.EMAIL.send({ to: ["user1@example.com", "user2@example.com", "user3@example.com"], from: { email: "newsletter@yourdomain.com", name: "Newsletter Team" }, subject: "Monthly Newsletter", html: "This month's updates
", text: "This month's updates", }); ``` ```bash curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/email/sending/send" \ --header "Authorization: BearerThis month'\''s updates
", "text": "This month'\''s updates" }' ``` List every recipient in the `To` header and pass one `--mail-rcpt` flag per address. ```sh cat > mail.txt <Your order is confirmed
", text: "Your order is confirmed", }); ``` ```bash curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/email/sending/send" \ --header "Authorization: BearerYour order is confirmed
", "text": "Your order is confirmed" }' ``` Add a `Cc` header for CC recipients. BCC recipients are added as `--mail-rcpt` flags but omitted from the headers. ```sh cat > mail.txt <Thanks for joining!
", text: "Thanks for joining!", }); ``` ```bash curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/email/sending/send" \ --header "Authorization: BearerThanks for joining!
", "text": "Thanks for joining!" }' ``` Use the `Display Name ` form in the `From` and `To` headers. ```sh cat > mail.txt <Monthly update
", text: "Monthly update", }); ``` ```bash curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/email/sending/send" \ --header "Authorization: BearerMonthly update
", "text": "Monthly update" }' ``` ```sh cat > mail.txt <Welcome ${firstName}!
Thanks for joining ${env.COMPANY_NAME}. Please verify your email to get started.
`, }); // Send verification email const verificationUrl = `https://${env.DOMAIN}/verify?token=${verificationToken}`; await env.EMAIL.send({ to: email, from: `noreply@${env.DOMAIN}`, subject: "Please verify your email address", html: `Verify Your Email
Hi ${firstName}! Click the link below to verify your email:
Verify EmailThis link expires in 1 hour.
`, }); return new Response( JSON.stringify({ success: true, message: "Account created. Please check your email.", userId, }), { status: 201 }, ); } async function handleVerification( request: Request, env: Env, ): PromiseEmail Verified!
Welcome ${user.firstName}! Your account is now active.
Continue `, { headers: { "Content-Type": "text/html" }, }, ); } function isValidEmail(email: string): boolean { return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); } ``` ## Next steps - [Email a login link](https://developers.cloudflare.com/email-service/examples/email-sending/magic-link/) — generate and email a link using a similar token pattern. - [Send method](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/) — full reference for the `send()` method. - [Deliverability](https://developers.cloudflare.com/email-service/concepts/deliverability/) — keep verification emails out of spam folders. Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/examples/email-sending/signup-flow/#page","headline":"User signup flow","description":"Handle user registration with automated welcome emails and email verification using secure tokens.","url":"https://developers.cloudflare.com/email-service/examples/email-sending/signup-flow/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/examples/email-sending/signup-flow/og.png?v=f5044c8c07ca08ef","dateModified":"2026-10-15","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Send transactional emails through Cloudflare Email Service authenticated SMTP from curl, Node.js, Python, or PHP. title: Send email over SMTP image: https://developers.cloudflare.com/email-service/examples/email-sending/smtp/og.png?v=be928fd6861ebc8d --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Send email over SMTP Send transactional emails over Cloudflare Email Service SMTP using curl, Nodemailer, Python smtplib, or PHPMailer. Last updated Jun 9, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/examples/email-sending/smtp/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Send transactional emails over Cloudflare Email Service [authenticated SMTP](https://developers.cloudflare.com/email-service/api/send-emails/smtp/) (`smtp.mx.cloudflare.net:465`) from any SMTP-capable language or client. ## Prerequisites - A domain onboarded for [Email Sending](https://developers.cloudflare.com/email-service/configuration/domains/). - A [Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with the **Email Sending: Edit** permission. Set it as `CF_API_TOKEN` in your environment. The token is used as the SMTP password; the username is the literal string `api_token`. ### Send an email ```sh cat > mail.txt <Welcome to Acme
Thanks for signing up.
", }); console.log("Message sent:", info.messageId); ``` ### Send with an attachment ```js const info = await transporter.sendMail({ from: '"Acme Billing"Welcome to Acme
Thanks for signing up.
", subtype="html", ) with smtplib.SMTP_SSL("smtp.mx.cloudflare.net", 465) as s: s.login("api_token", os.environ["CF_API_TOKEN"]) s.send_message(msg) ``` `smtplib.SMTP_SSL` opens an implicit-TLS connection on port `465`, which is what Cloudflare's SMTP endpoint requires. Do not use `smtplib.SMTP` with `starttls()`; `STARTTLS` is not supported. ### Send to multiple recipients ```python msg["To"] = ", ".join([ "user1@example.com", "user2@example.com", "user3@example.com", ]) ``` A single SMTP session can deliver to up to 50 `RCPT TO` addresses. See [Limits](https://developers.cloudflare.com/email-service/platform/limits/). ### Send with an attachment ```python from pathlib import Path pdf = Path("invoice-2026-04.pdf").read_bytes() msg.add_attachment( pdf, maintype="application", subtype="pdf", filename="invoice-2026-04.pdf", ) ``` ### Error handling `smtplib` raises subclasses of `smtplib.SMTPException` with the SMTP reply code attached. See [SMTP response codes](https://developers.cloudflare.com/email-service/api/send-emails/smtp/#response-codes) and [Troubleshooting](https://developers.cloudflare.com/email-service/api/send-emails/smtp/#troubleshooting). ```python try: with smtplib.SMTP_SSL("smtp.mx.cloudflare.net", 465) as s: s.login("api_token", os.environ["CF_API_TOKEN"]) s.send_message(msg) except smtplib.SMTPAuthenticationError as e: print(f"Auth failed: {e.smtp_code} {e.smtp_error!r}") except smtplib.SMTPResponseException as e: print(f"SMTP error: {e.smtp_code} {e.smtp_error!r}") ``` ### Send an email ```php isSMTP(); $mail->Host = 'smtp.mx.cloudflare.net'; $mail->Port = 465; $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS; $mail->SMTPAuth = true; $mail->Username = 'api_token'; $mail->Password = getenv('CF_API_TOKEN'); $mail->setFrom('welcome@yourdomain.com', 'Acme'); $mail->addAddress('recipient@example.com'); $mail->Subject = 'Welcome to our service!'; $mail->Body = 'Thanks for signing up.'; $mail->send(); ``` ## Next steps - [SMTP reference](https://developers.cloudflare.com/email-service/api/send-emails/smtp/) — connection details, authentication, response codes, and troubleshooting. - [Specify recipients](https://developers.cloudflare.com/email-service/examples/email-sending/recipients/) — multiple recipients, CC and BCC, and named addresses. - [Limits](https://developers.cloudflare.com/email-service/platform/limits/) — account, message, and session limits. Was this helpful? YesNo ## On this page [Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org/","@type":"TechArticle","@id":"https://developers.cloudflare.com/email-service/examples/email-sending/smtp/#page","headline":"Send email over SMTP","description":"Send transactional emails through Cloudflare Email Service authenticated SMTP from curl, Node.js, Python, or PHP.","url":"https://developers.cloudflare.com/email-service/examples/email-sending/smtp/","inLanguage":"en","image":"https://developers.cloudflare.com/email-service/examples/email-sending/smtp/og.png?v=be928fd6861ebc8d","dateModified":"2026-06-09","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Remove recipients after hard bounces and spam complaints. title: Sync recipient records image: https://developers.cloudflare.com/email-service/examples/email-sending/sync-recipient-records/og.png?v=d551728e3df5df76 --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/email-service/llms.txt > Use this file to discover all available pages before exploring further. # Sync recipient records Synchronize application recipient records with Email Sending lifecycle events. Last updated Oct 15, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/email-service/examples/email-sending/sync-recipient-records/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Use [Email Sending event subscriptions](https://developers.cloudflare.com/email-service/reference/event-subscriptions/) to update application records after delivery problems. This example uses [Cloudflare Queues](https://developers.cloudflare.com/queues/) and [Workers KV](https://developers.cloudflare.com/kv/) to remove recipients from transactional notifications. Suppression lists Email Sending automatically [suppresses](https://developers.cloudflare.com/email-service/concepts/suppressions/) hard bounces and spam complaints. This example also prevents your application from selecting those recipients. Workers KV is eventually consistent. Deletions can take 60 seconds or longer to appear in other locations. ## Prepare the resources Before you begin: - Enable an [Email Sending domain](https://developers.cloudflare.com/email-service/configuration/domains/). - Create a [Worker project](https://developers.cloudflare.com/workers/get-started/guide/). - Create a [Workers KV namespace](https://developers.cloudflare.com/kv/get-started/#2-create-a-kv-namespace). Store each eligible recipient address as a key in KV. The value can contain notification preferences or related metadata. ## Review the event flow 1. Email Sending publishes bounce and complaint events. 2. A queue delivers those events to a Worker. 3. The Worker removes ineligible recipient records from KV. ## Choose removal events Remove records for every `message.complained` event. These events indicate that a recipient reported the message as spam. Remove bounced records only when `payload.bounce.type` is `"hard"`. Temporary failures produce `message.deferred` events while retries remain. Exhausted temporary retries can produce `message.bounced` events with a `"soft"` bounce type. For payload details, refer to [Available Email Sending events](https://developers.cloudflare.com/email-service/reference/event-subscriptions/#available-email-sending-events). ## Create the queue and subscription Create a queue and subscribe it to your sending domain: 1. In the Cloudflare dashboard, go to the **Queues** page. Create a queue named `email-events`. [Go to **Queues** ↗](https://dash.cloudflare.com/?to=/:account/workers/queues) 2. Select `email-events`, then select **Subscriptions** > **Subscribe to events**. 3. Enter a subscription name and select **Email Sending** as the source. 4. Select your sending domain and the `message.bounced` and `message.complained` events. 5. Select **Subscribe**. ## Configure the Worker Bind the KV namespace and register the Worker as the queue consumer: ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "recipient-record-sync", "main": "src/index.ts", "upload_source_maps": true, // Set this to today's date "compatibility_date": "2026-10-18", "kv_namespaces": [ { "binding": "RECIPIENTS", "id": "Thank you for contacting support. Your ticket number is 123.
A member of our support team will get back to you shortly.
", }); const replyMessage = new EmailMessage( `support@${YOUR_DOMAIN}`, message.from, msg.asRaw(), ); await message.reply(replyMessage); // Forward to support team await message.forward(FORWARD_TO_EMAIL); } else { // Default: forward to admin await message.forward(FORWARD_TO_EMAIL); } }, } satisfies ExportedHandlerWelcome!
Thanks for signing up.
", text: "Welcome! Thanks for signing up.", }); return new Response(`Email sent: ${response.messageId}`); }, } satisfies ExportedHandlerWelcome!
Thanks for signing up.
", "text": "Welcome! Thanks for signing up." }' ``` A successful response includes the delivery status for each recipient: ```json { "success": true, "errors": [], "messages": [], "result": { "delivered": ["recipient@example.com"], "permanent_bounces": [], "queued": [] } } ``` For more details, see the [REST API reference](https://developers.cloudflare.com/email-service/api/send-emails/rest-api/). Send an email with a single `curl` command. Replace `Node.js version manager
Use Vite+ (vp env) ↗︎ to install and manage Node.js versions.
For supported Node.js versions, refer to the Wrangler system requirements.
Node.js version manager
Use Vite+ (vp env) ↗︎ to install and manage Node.js versions.
For supported Node.js versions, refer to the Wrangler system requirements.