Dify email delivery configuration

Why Dify email delivery configuration decides whether users can get in

A new workspace member who never receives an invitation, or a password reset that fails without any visible error, stops the onboarding plan cold. In a self-hosted Dify, several core flows depend on outbound email: workspace invitations, password resets, ownership transfers, email verification codes and human input forms that pause a workflow until a reviewer responds. If mail does not leave the platform, the people who need access cannot get it, and the reviewers who should approve a workflow never see the request. Email is a separate outbound path from model and tool traffic, so a working model provider connection tells you nothing about whether messages will be delivered.

Treat mail as a go-live dependency rather than a later convenience. Decide which provider you will use (Resend, SMTP or SendGrid, as the Dify environment reference documents), who owns its credentials and sending domain, and how the sender address is set up before the first real user is invited. Test each flow with a real external mailbox: send an invitation, complete a password reset, trigger an email code and submit a human input form notification. Repeat the test after every upgrade, because environment variables can change between releases.

Confirm the exact variable names, required values and any provider-specific fields in the Dify environment variable reference, since those names are the authoritative source for your version. Ask your mail provider whether your sending domain has the DNS records it requires and whether your network allows outbound connections to its SMTP or API endpoint. If your deployment routes outbound traffic through a proxy, check that mail is not blocked by the same rules that govern tools and HTTP nodes. A mail check takes little time compared with discovering on launch day that no invitation has ever left the server.

Choosing Resend, SMTP or SendGrid for Dify mail

This table compares the three mail paths for Dify by the situation that makes each one fit, along with what the team must provision, where credentials live, which egress to allow and who owns deliverability. Read each row against your existing mail contracts, because the right choice usually follows from what your organization already operates. The main takeaway is that the provider decision sets the ongoing work, so settle ownership before the first invitation is sent.

Decision point	Resend (cloud API)	Internal or corporate SMTP relay	SendGrid (cloud API)
When it fits	Your team already holds a Resend account or wants a sender domain managed through a transactional API	Your IT group already runs a relay that handles corporate mail and can accept an authenticated application sender	Your organization already has a SendGrid contract or existing transactional sending practice
What you must provision	A verified sender domain with the DNS records Resend requests, and an API key for Dify	A relay account or allowed host for the Dify mail server, with a sender address and authentication method approved by mail operations	A verified sender identity or domain in SendGrid, and an API key with mail send permission
Where credentials are stored	In the Dify environment file as secret values, with the file protected at the host and restricted to the operators who deploy Dify	In the environment file or a secrets manager, with the SMTP password treated as a secret and rotated under your mail policy	In the environment file or a secrets manager, with the API key treated as a secret and rotated under your key policy
Network egress to allow	Outbound HTTPS from the Dify API and worker containers to the Resend API endpoint, routed through any approved proxy	Outbound connection from the Dify containers to the relay host and port, usually with TLS, and allowance on the relay for the Dify source address	Outbound HTTPS from the Dify containers to the SendGrid API endpoint, routed through any approved proxy
Who owns deliverability	Your team owns DNS, domain reputation and bounce handling, with the provider supplying sending infrastructure	Your mail operations group owns SPF, DKIM, DMARC, reputation and queue handling for the relay	Your team owns DNS, sender authentication and reputation, with the provider supplying sending infrastructure
Vendor pricing and plan limits	Set by the provider and must be confirmed with Resend before you rely on a volume assumption	Usually set by internal chargeback or licensing; confirm with the relay owner	Set by the provider and must be confirmed with SendGrid before you rely on a volume assumption
Where the choice is made	In the Dify environment settings used at deployment, not in the Dify console	In the Dify environment settings used at deployment, not in the Dify console	In the Dify environment settings used at deployment, not in the Dify console
What to confirm before choosing	Domain verification steps, API key scopes and whether your proxy rules permit the endpoint	Relay authentication mode, TLS support, allowed sender addresses and rate limits on the relay	Domain verification steps, API key scopes and whether your proxy rules permit the endpoint

Which Dify emails fail first when delivery is misconfigured

Five Dify emails carry the most weight for users: invitations, password resets, ownership transfers, verification codes and human input notifications. They share two failure points: the mail path itself and the host name written into each link. Test every flow in a staging instance before production, and confirm each trigger against the Dify docs for your version.

Workspace invitations

A new team member waits for an invitation before they can sign in or start building. The usual symptom is an invitation that never arrives, or one whose accept link opens the wrong address. Check the sender address and the provider's domain rules first. Then open the link and confirm its host matches the public console address you configured. Invite a test mailbox in staging before inviting real staff, and check that the message arrives in the inbox, not in spam.

Password resets

A locked-out user is waiting for a reset link that expires after a short period. Operators often see the message land in spam, or see a link that points to localhost or an internal hostname because the public web address was never set. Check the console and web URL settings in your .env file first. Then confirm SPF, DKIM and DMARC records for the sending domain. Request a reset from a test account and follow the link end to end.

Ownership transfers

During an ownership transfer, the incoming owner waits for a confirmation email before the change takes effect. A common symptom is a request that appears to succeed while nothing changes, because the confirmation was never received or never clicked. Confirm in the docs and in staging which step sends the email and who must act on it. Check the mail provider's log for the recipient before asking anyone to resend.

Email verification codes

A sign-up or sign-in code is useful only for a short window, so delay matters more here than in other flows. A code that arrives late is effectively lost. Watch for provider rate limits during bursts of sign-ups, sender names that spam filters distrust, and sign-up policies that block domains you did not expect. Check the provider dashboard for rejected or deferred messages before changing Dify settings.

Human input form notifications

A workflow paused at a human input step waits for a reviewer to receive a notification and open a form. If the email never arrives, the run stays paused and nobody sees the request. Confirm which reviewer address the node uses, then start a paused run in staging and check the notification end to end. Verify that the form link resolves to the public host, not an internal name, so reviewers can complete it from outside the network.

How to set up and test Dify email delivery in order

This sequence takes a self-hosted Dify from no outbound mail to verified delivery of every transactional email type, with each step closed by a check the operator can run. It works the same way whichever provider (Resend, SMTP or SendGrid) the team chooses.

Choose the mail provider and confirm the plan
The platform team picks Resend, SMTP or SendGrid, based on what the organization already contracts for and what its security team approves for sending mail. Confirm that the account can send to external recipients and that sending limits and data processing terms meet internal policy, since these are set by the provider and not by Dify. Done when the team has a written provider choice and an account with API or SMTP credentials that the security team has accepted.
Create the sender identity and verify the domain
An administrator creates a sender address on a domain the organization controls, such as a no-reply address for the Dify console. The provider will require ownership proof for that domain, which the admin completes in the provider's console. Done when the provider shows the sender identity and sending domain as verified and no pending warnings remain.
Add the DNS records the provider requires
The DNS administrator adds the records the provider lists for the sending domain, typically for domain verification, SPF and DKIM signing, and any tracking or bounce handling the provider offers. Record values come from the provider console and should be copied exactly, because a single typo blocks verification. Done when the provider reports the records as found and a DNS lookup from outside the network returns the expected values.
Set the mail variables in the environment file
The operator sets the mail-related variables in the .env file used by Docker Compose, using the names in the Dify environment variable reference for the installed version. Confirm each variable name and its accepted values against the version's .env.example, and keep credentials out of shared chat and tickets. Use the public URL setting so links in emails point to the correct host. Done when the file contains the chosen provider's values and a config review shows no placeholder text left in place.
Restart the affected services and confirm they came up
The operator applies the new environment to the containers that read it, following the restart procedure in the Docker Compose documentation for the installed version. Mail is sent from the API and worker services, so both must pick up the change. Check container status and logs for startup errors such as failed authentication or missing variables. Done when all relevant containers report healthy and the logs show no mail configuration errors.
Send a test message for each email type
Using a non-production account and a test mailbox that the team controls, the admin triggers each flow: invitation, password reset, ownership transfer, email verification code and a human input form notification where the workflow uses one. Record the time each message was sent and whether it arrived. Done when every email type has arrived in the test mailbox or the failure is logged with the matching log line.
Check headers and links in each received message
Open the raw headers of each test message and confirm that SPF and DKIM both pass for the sending domain and that the DMARC result aligns with the From address. Then click the links in the invitation and reset emails and confirm they resolve to the public Dify URL configured in the environment, not an internal or placeholder address. Done when every message shows passing authentication results and every link lands on the expected host over HTTPS.
Confirm the sequence and document the result
Record the provider, sender address, variable names used (without secret values), the restart steps taken and the test results in the operations runbook. Repeat the checks after any Dify upgrade, because the mail settings and templates can change between versions, and confirm the new behavior against the release notes. Done when the runbook names the owner of the mail configuration and the last date each email type was verified.

Sender identity, DNS and the links inside each email

The sender address, the sending domain and the public base URL that Dify uses to build links must describe the same organization and the same host. Dify writes invitation, password reset and ownership transfer links from its own configuration, so a base URL that points at an internal name, an old hostname or a plain IP address sends your users to the wrong place even when the message itself arrives. Mismatched sender domains also make receiving servers less willing to accept the message. Before you change anything in the mail settings, decide three values together: the address Dify sends from, the domain that owns that address, and the single public URL your users will open. Confirm the exact variable names for the base URL and sender address against the Dify environment variable reference for your release, because these names have changed across versions and the file you copied from an older deployment may not match.

The DNS work belongs to whoever administers the sending domain, which is often a mail or IT team rather than the platform team running Dify. SPF, DKIM and DMARC records are published under that domain, and only its owner can create or change them. Ask the mail administrator to confirm which service actually sends on behalf of the domain (Resend, your SMTP relay or SendGrid), to publish the records that service requires, and to tell you how long a change takes to propagate. Do not let the platform team edit records under a domain it does not own, and do not ask the mail team to approve a sender address they have not seen written down. Agree on a short written record that lists the sender address, the sending service, the owner of each DNS record and the date each record was last verified. Then, after the records are live, send a test message from Dify and check the headers and the link it contains. The reader should confirm the record values with their chosen provider and their own DNS team, since the correct values depend on the provider they select.

Protecting mail credentials, recipients and the links in mail

Mail from Dify carries credentials of its own: provider API keys or SMTP passwords, one-time codes and reset links that act like logins. The cards below cover where those secrets live, which network paths can reach the provider, how the sender identity is scoped and how long mail-borne tokens remain valid.

Store mail secrets in your existing vault

Keep the Resend API key, SendGrid key or SMTP password out of plain .env files committed to source control. Load them from the secrets handling your team already runs, inject them at container start, and restrict who can read the host's environment. Rotate the key on a schedule and after any staff change. Because SECRET_KEY already protects session data, confirm your backup copies of .env are encrypted and access-controlled as well.

Limit network paths to the provider

Only the Dify component that sends mail needs a route to the mail provider. Allow outbound traffic to the provider's SMTP or HTTPS endpoint from that host or container, and deny other egress by default. Dify's SSRF proxy controls outbound requests made by tools and nodes, and it blocks internal and private IP ranges. Confirm in your Compose layout whether mail traffic follows that same egress path, or whether it leaves through a separate route that your firewall must also govern.

Use a dedicated sender identity

Create a sending domain or sender address used only by Dify, with its own API key or SMTP account. Restrict that credential to sending mail, and do not reuse a key that other business systems already hold. Keep SPF, DKIM and DMARC records for that domain under change control. If the same credential can send for your ticketing or marketing tools, a leaked Dify key exposes those systems too.

Treat codes and reset links as credentials

A password reset link or email code lets whoever opens it take over an account until it expires or is used. Confirm the lifetime Dify applies to each token type in your version, and keep those lifetimes short in your own configuration where Dify exposes the setting. Avoid forwarding these emails through shared inboxes or logging full message bodies in your mail relay. Ask your mail provider how long it retains message content.

Protect recipients and human input links

Human input forms send links to people outside the build team, so the recipient list and the link itself both need control. Limit who can add addresses to invitations and ownership transfers, and review the recipient fields in workflows that send mail automatically. Treat each form link as access to a workflow step, not as a public web page. Check how your version expires these links before you promise a review window to stakeholders.

Verify the mail path after each upgrade

Minor Dify releases arrive about monthly, and environment variable names and mail behavior can change between them. After every upgrade, compare your .env against .env.example, confirm the sender identity and credentials still work, and send a test invitation to an internal mailbox. Record which provider, sender and credential were used, so a later security review can trace which mail path was active on a given date.

What to confirm for each mail path before you rely on it

Resend is an API-based sending service, so the questions focus on the sending domain, the account plan and how your Dify version reads the provider settings. Limits and plan terms change, so take them from the provider's current documentation and confirm them against the volume you expect from invitations, resets and form notifications.

Sending limits and plan terms: Ask the provider for the current daily and monthly sending limits on your plan, and for what happens when you exceed them.
Domain verification: Confirm the DNS records the provider requires for your sending domain, who controls that DNS zone, and how long verification takes in your environment.
Bounce and complaint handling: Confirm how bounces and spam complaints are reported, who receives them, and whether suppressed addresses block future sends from Dify.
Dify version support: Check the Dify environment reference for the Resend settings in the version you run, and confirm the variable names and the API key format in a staging instance.
Data location and retention: Ask where message content and logs are stored and how long they are kept, since invitation and reset emails contain account-related information.

Confirm each item in writing with the provider and test a real invitation on staging before you rely on the path in production.

Questions teams ask before they configure Dify email

How much effort does Dify email configuration take?

The effort depends mainly on three things: the mail provider you choose, how much DNS access your team has, and how many environments need working mail. Setting one provider in one environment is a small change to the Dify environment file plus a few DNS records. Each environment and each message type then needs its own test. Invitations, password resets, ownership transfers, email codes and human input forms all send mail, so each one needs a check. Mail provider charges are separate from Dify, and each provider's pricing page sets them. Ask any partner to split a quote into provider setup, DNS work, testing per environment and handover.

Can our own team configure Dify email without outside help?

Yes, if the team has Docker Compose experience, DNS administration skills and access to the mail provider console. The work involves editing the .env file based on .env.example, restarting the affected containers, creating sending domains and publishing the DNS records your provider specifies. When a message does not arrive, someone must read the api and worker logs to find out why. Most gaps appear in DNS change control, sending domain verification and testing human input forms, which only fire when the workflow runs. Decide who owns each step before you start.

How long does Dify email setup take with DNS and approvals?

The schedule depends mostly on people and systems outside the Dify installation: DNS change approval, domain verification at the provider and security sign-off on a new sending identity. Ask your DNS team how long its change window runs, and ask your mail provider how long domain verification takes on your account type. Once records are published, the Dify side is usually a configuration change followed by a test pass. DNS propagation timing varies, so plan test windows across several days rather than a single session. Confirm these lead times in writing before you commit to a go-live date.

What does a fixed-scope Dify email engagement include?

A fixed-scope engagement starts with a written scope agreed before work begins. It typically covers provider selection support, configuration of the chosen provider in each agreed environment, DNS record guidance, test runs for each agreed message type and a handover to your team. Deliverables and timing are set in that written scope. You provide a named DNS owner, provider account and admin access, the list of environments and domains, sender address decisions, approval contacts, test mailboxes and access to the Dify hosts. Ask the quote to list each message type and test case it covers.

What recurs after Dify email goes live?

Several items recur. Provider plans and pricing change, domains and DNS records need renewal, API keys or SMTP credentials need rotation, and sender addresses sometimes change. Dify upgrades also touch mail. Dify ships minor releases roughly monthly, so plan for regular upgrade reviews. Back up before every upgrade, check .env.example for new variables, and then retest invitations, password resets and email codes. The Dify Docker Compose guide describes the upgrade steps for each target version.

Does DeployOpen run the Dify email test matrix?

DeployOpen can plan and run the mail test matrix as part of a written, fixed-scope engagement, and it offers retainers if you want checks after go-live. Confirm in the scope which combinations are covered: each provider, each environment and each message type, including invitations, password resets, ownership transfers, email codes and human input forms. Also confirm delivery to your own mail domains and spam placement checks. DeployOpen does not issue audit reports or certifications, so the test results support your own review and documentation.

Which mail provider should we choose for Dify?

Choose based on your existing mail infrastructure, sending volume, data location requirements and who will administer the service. This topic covers Resend, SMTP and SendGrid. Mail costs come from the provider, so compare each provider's pricing page, while the self-hosted Dify Community edition is free and limited to a single workspace. Ask your security team whether it accepts each provider as a processor of message content, and where that content is stored. Before you decide, ask each provider how it handles domain verification and DNS records for your domain.

How DeployOpen scopes and delivers Dify email configuration

DeployOpen plans, configures and documents outbound email for a self-hosted Dify inside your own infrastructure, so invitations, password resets and human input forms reach the people who need them. We start from the mail provider you have approved and the sender domain you control, then deliver a tested configuration your team can operate.

How we scope

Confirm which mail path you approve: Resend, SMTP or SendGrid, and who owns the sending domain
Inventory the email flows you rely on: invitations, resets, ownership transfers, email codes and human input forms
Record where Dify runs, how outbound traffic leaves your network and which proxy or allowlist rules apply
Agree the written scope, deliverables and timeline before work starts, since engagements are fixed-scope

How we build

Set the mail provider variables in your Compose or deployment configuration, with secrets kept out of source control
Verify sender domain records and confirm the outbound path passes the SSRF proxy rules in your environment
Test each email flow end to end in a non-production instance, including links that point to the correct public address
Review logs for delivery errors and document the failure signals your operators should watch for

How we hand over

Deliver a written configuration record listing variables, provider settings and the sender identity in use
Provide a test runbook your team can repeat after upgrades, provider changes or credential rotation
Document how to rotate mail credentials without logging out users or breaking pending invitations
Walk your operators through the checks and the escalation path for failed deliveries

How we support

Ongoing support, upgrades and continuous testing are available as retainers, scoped in writing
Re-test email flows after each Dify upgrade, since release notes and new variables can change behavior
Check the configuration reference again when you change mail providers or sending domains
Ask for a quote based on your written scope, environment and support expectations