ERPNext email setup and delivery troubleshooting

Why ERPNext email setup decides whether invoices and alerts arrive

ERPNext sends invoices, payment reminders, scheduled reports and user notifications, and it depends on staff replies coming back into the system, so email is part of the financial workflow, not an add-on. Email must be configured per email account, the default outgoing and incoming accounts must point at the right mailboxes, and delivery depends on the SMTP provider and the sending domain. If any one of those three is wrong, documents can look sent inside ERPNext while the recipient never sees them, and the failure often surfaces weeks later as an unpaid invoice or a missed alert.

Most teams can configure a single account in an afternoon. The harder work is deciding which account sends which kind of mail, confirming that the domain's authentication records match the provider, and checking that replies route to a mailbox someone actually monitors. Those decisions touch your DNS, your mail provider contract and your internal ownership of the shared inbox, so they should be made deliberately before go-live. A team should ask for outside help when invoices or reminders are going missing, when several companies or sites share one domain, or when a bounce or spam complaint is hard to trace to its cause.

This page walks through the components involved: email accounts and domains, default incoming and outgoing accounts, SMTP provider setup including the SendGrid path that ERPNext documents, retries, and the checks to run when an email does not reach its recipient. Confirm your provider's current sending limits and authentication requirements directly with them, since those terms change independently of ERPNext.

Email account options and when each fits

This table compares the outgoing SMTP account, the incoming IMAP or POP account, the default outgoing and incoming settings, and a hosted SMTP relay. Read each row against the mail flow you need, since most ERPNext sites use outgoing mail first and add incoming mail only where users reply to or receive documents. The main takeaway is that outbound delivery depends on your sending domain's reputation, so the sending path matters as much as the account settings.

Option	When it suits	Main trade-off
Outgoing SMTP account	Your organization already runs a mail server or hosted mailbox that permits application sending for ERPNext's notifications and document emails	Delivery depends on your mail host's sending limits and on SPF, DKIM and DMARC being set correctly for your domain
Incoming IMAP account	Users reply to ERPNext emails and replies should attach to the related document, such as a sales order or issue	ERPNext polls the mailbox, so replies arrive with a delay and the mailbox needs a dedicated, well-managed account
Incoming POP account	The mail host only offers POP access and you accept that messages are typically downloaded and removed from the server	Less suited to shared mailboxes or keeping a server-side copy, so confirm retention behavior with your provider
Default outgoing account	One sending account should cover all sites and modules so that notifications use a consistent sender identity	A single default can send all system mail, so a failing account stops notifications across the site
Default incoming account	You want replies and inbound messages routed through one controlled mailbox tied to your Email Domain setup	Mail for other mailboxes may not be routed as expected, so test each email account that receives mail
Hosted SMTP relay (for example SendGrid)	High volumes of notifications or documents, or a need for the provider's delivery tooling and sending reputation	Adds a third-party service, API key handling and a DNS and domain verification step to maintain
Mailbox on the same host as ERPNext	Small internal deployments where the local mail service is already operated and monitored	You take on mail hygiene, blocklist monitoring and deliverability work yourself

How to configure ERPNext email step by step

This sequence takes ERPNext from a sending domain with confirmed DNS records to a tested outgoing and incoming email setup, with a checked queue and error log at each stage. The result is a configuration you can trust before users depend on it for notifications and replies.

Confirm the sending domain and DNS records
Your team confirms which domain ERPNext will send from and asks the mail provider which DNS records that domain needs for authentication. Typically this covers SPF, DKIM and DMARC, but the exact records, selectors and values come from your provider, not from this page. Work with the person who manages DNS and record each record and its expected value. You know this step is done when the provider's own verification shows the domain as authorized and the records resolve from outside your network.
Create the outgoing email account and set default
In the ERPNext desk, an administrator creates an Email Account for outgoing mail, enters the SMTP host, port, encryption and credentials your provider issued, and marks it as the default outgoing account. Confirm these values with your provider, including whether the account needs a dedicated sending user or an API key in the password field. Save the account, then use the account's test option if it is available in your version. The step is complete when the account is saved, shows as default, and the test does not produce an authentication or connection error in the Error Log.
Configure incoming accounts for replies
Create an incoming Email Account for the mailbox that receives replies, such as a support or documents address. Enter the IMAP or POP settings your provider documents, and decide whether replies should create or append to documents through the email inbox behavior your version offers. Confirm the mailbox folder, the polling behavior and whether the provider requires app-specific credentials. The step is done when a message sent to that address appears in the Email Inbox or the Communication list linked to the right document, without errors in the Error Log.
Confirm the scheduler and email queue are running
Outgoing mail in ERPNext passes through the Email Queue, and incoming polling depends on scheduled jobs. Your platform or operations team confirms that the scheduler is enabled for the site and that background workers are processing the default queue. Check the Email Queue list for pending items and confirm that they move to sent or failed status over time. If nothing moves, the problem is usually the scheduler or worker, not the mailbox settings. The step is done when a queued message changes status without manual intervention.
Send a test message to an internal address
Send a test email from ERPNext to an address inside your organization, using a simple document notification or a test from the email account. Your administrator then checks the Email Queue for the message, its status and any error text, and confirms that the message arrives with the sender name and domain you expect. Reply to the message from the internal mailbox to exercise the incoming account. The step is done when the outgoing message is marked sent, the reply is captured in ERPNext, and the Error Log shows no new entries for the test.
Send a test message to an external address
Repeat the test with an address at an external provider you can access, such as a personal or partner mailbox your team controls. External delivery exposes problems that internal tests miss, including sender authentication failures and spam filtering. Check the message headers at the recipient for SPF, DKIM and DMARC results, and confirm the envelope and From addresses match your configured domain. The step is done when the message reaches the external inbox, the headers show passing authentication, and the Email Queue status is consistent with what the recipient received.
Review the Error Log and document the baseline
Before you hand the setup to users, review the Error Log and the Email Queue for any failed or repeated entries from the tests. Record the working account names, default flags, DNS records, provider settings location and the names of the people who can change each one. Keep this record with your runbook so later troubleshooting starts from a known state. The step is complete when the log shows no unexplained errors from the tests and the baseline record has been reviewed by the administrator and the owner of DNS.

Why emails are not reaching recipients

Start inside ERPNext, because many delivery problems never leave the application. An email can be created and sit in the outgoing queue without being sent, which usually means the process that sends queued mail is not running or is not reaching the queue. The default outgoing account can also be wrong, so messages are sent through an account that is disabled, belongs to another domain, or was never configured for the function that triggered the email.

Email Queue status: Open the Email Queue list and check whether messages stay in Not Sent or show errors. Messages that never leave the queue point to the sending process rather than the provider.
Background workers and scheduler: Confirm that the workers and the scheduler are running for the site. Ask your team which processes handle email in your deployment and how they are monitored.
Default outgoing account: Check the Email Account settings to see which account is the default for outgoing mail and whether it is enabled for sending.
Per-function accounts: Confirm which account sends notifications, document emails and automated reports, since some functions can be pointed at a different account.
Error Log: Review the Error Log for SMTP exceptions and connection failures raised when messages are processed.

If the queue is empty and nothing appears in the sent log, the fault is upstream of the provider, so do not change provider settings yet.

How queued emails and retries behave

ERPNext sends most outgoing mail through a background queue, so a message can be accepted by the application and still fail later. The cards below cover the queue itself, how failures are recorded and retried, and the checks to make before anyone resends a message by hand.

The outgoing email queue

Most system and document emails are written to the Email Queue doctype first and then sent by a background worker, so the desk save can succeed while delivery is still pending. Operators should open Email Queue and filter by status to see what is waiting, sending, sent or failed. Confirm which queue the worker reads on your version and whether emails are sent in the short or default queue, since a backed-up queue delays everything behind it.

Failed sends and retries

A send that fails because the SMTP server refuses the connection, times out or rejects credentials usually leaves the queue entry in a failed state with the error text recorded on it. Read that error before doing anything else, because a credentials or sender-domain problem will fail again on every retry. Confirm on your ERPNext version whether failed entries are retried automatically, how many attempts are made, and when they are abandoned.

Checks before resending

Before resending, confirm the original message did not actually reach the recipient, since mail servers can deliver late after a timeout reported as a failure. Check the SMTP provider's sending logs for the recipient and the message subject, and fix the root cause such as the outgoing account, sender domain or provider limit. Only then resend, and note who did it and why.

Duplicate risk on manual resends

Resending a failed email from the queue or re-triggering the action that created it can produce a duplicate, which is a real problem for invoices, payment reminders and approval notices. The message may have been accepted by the provider even though ERPNext recorded a failure. Ask the recipient or check the provider log first, and avoid re-running the document action that generated the mail unless you have confirmed nothing was delivered.

Confirm retry behavior on your version

Retry rules, queue names and the handling of failed entries can change between ERPNext major versions, and the version in use determines what the worker does. Test a deliberately failed send on a staging site with the same outgoing account and worker setup as production. Record the observed attempt count and final state, and have the result reviewed before relying on automatic retries for business-critical mail.

Security settings for email credentials and sending domains

Email in ERPNext runs on credentials that can send mail as your company, so the account settings, the people who can edit them and the DNS records for your domain all need the same care. The cards below cover the controls to review before and after go-live, and what to confirm in your own environment.

Store SMTP passwords as protected fields

Each Email Account in ERPNext holds the password used to authenticate to the outgoing server. Confirm that the password field is stored in the way your ERPNext version protects it, and that the value is entered once rather than copied into notes, tickets or shared spreadsheets. Check that your backups are treated as holding these secrets, since a restored database carries whatever was saved. Use one password per Email Account so that rotating one sender does not break others.

Limit who can edit Email Accounts

Changing an Email Account can redirect outgoing mail, change the sender address or expose stored credentials, so editing rights should be narrower than viewing rights for most users. Review which roles can open the Email Account doctype and whether any custom role or script grants access by accident. Confirm who may set the default outgoing and incoming accounts, because those defaults decide where system mail is sent from for the whole site.

Use dedicated sending credentials

Create a mailbox or SMTP identity used only by ERPNext, separate from any personal account and from the mailbox your staff read. Scope it to sending, where your provider allows, and record which Email Account and which application use it. This separation makes a leaked credential easier to revoke without stopping staff email, and it keeps delivery logs at the provider attributable to ERPNext alone. Ask your provider which permission levels are available for SMTP sending identities.

Publish DNS authentication records

Receiving servers decide whether to trust ERPNext mail partly from the DNS records of the sending domain. Confirm with your email provider which SPF, DKIM and DMARC records it requires, and that the SPF record includes every server that sends for your domain, including ERPNext. Record who owns DNS changes and when a record was last verified. Missing or mismatched records are a common reason mail is filtered, so check them before you blame ERPNext's configuration.

Keep mailbox passwords out of logs and exports

Error logs, scheduled job records, data exports and support screenshots can reveal settings or credentials if they are shared without review. Before you export Email Account data or paste a traceback into a ticket, remove any credential or connection detail. Ask whether your team's log shipping or monitoring tools receive ERPNext logs and whether they mask values. Treat any credential that appears in a log as exposed and rotate it.

Rotate credentials on a schedule

Sending credentials should have a named owner, a rotation interval set by your security policy and a documented procedure. Rotation changes the password in ERPNext, the provider and any password manager at once, so test the new credential with a test email before retiring the old one. Confirm how your provider handles revocation and whether it notifies you of suspicious sending activity. Record each rotation so that an audit can see when the credential changed.

Questions teams ask before hiring help with ERPNext email

How much work does ERPNext email setup usually take?

The effort depends mainly on how many email accounts, domains, sending providers and mailboxes the setup covers, and on how clean the existing DNS and mail records are. A single domain with one outgoing SMTP provider and one shared inbox is a small job. Multiple companies, several domains, separate sending streams for invoices and notifications, and inbound mail routed into ERPNext as Email Accounts each add configuration and testing steps. Ask any partner to break the estimate into accounts, domains, providers and test cases so you can see where the time goes before you agree to a scope.

Can an in-house administrator set up ERPNext email alone?

Often yes, if the administrator has access to the ERPNext Email Account settings, the DNS zone for the sending domain and the account at the SMTP provider. The work involves creating outgoing and incoming Email Accounts, choosing the default accounts, verifying sender domain records and sending test messages to several recipient types. The harder part is diagnosing messages that are accepted by the provider but never reach the inbox, because that needs access to provider logs and recipient mail headers. If your team has no one who reads those logs or edits DNS confidently, a partner can cover that gap.

What does our team need to provide before work starts?

Prepare four things before the first session:

DNS access, or a named person who can add and change records for each sending domain
An account at the SMTP provider you plan to use, with API or SMTP credentials and permission to verify domains
Access to the ERPNext site, with a user who can manage Email Accounts and Email Domains
Test recipients on mailboxes you can check, including at least one external provider and one internal address

Also confirm who approves changes to production mail, since a wrong SPF or DKIM record can stop all outgoing invoices.

What does a fixed-scope ERPNext email engagement cover?

A fixed-scope engagement covers the items agreed in writing before work starts, usually the listed Email Accounts, domains, providers, default account choices, inbound routing and the test cases that prove each path works. It should also state what is out of scope, such as mailbox migration, changes to your wider mail platform or work on other ERPNext modules. Deliverables should include a configuration record, a test log and a short runbook for the team. Compare any proposal against the written scope rather than a general description of email work.

How is ongoing email delivery monitoring handled?

Monitoring after go-live is a separate decision from the initial setup. It usually means reviewing bounce and failure records in ERPNext, checking that scheduled email jobs run, watching provider dashboards for blocked or deferred messages and rechecking DNS records when the domain changes. These tasks can stay with your team or move to a support retainer. Ask any partner who would receive alerts, how quickly a failure is triaged and what is excluded from the retainer, such as provider-side policy decisions.

What drives the cost of email delivery work up or down?

Cost follows the same drivers as effort: the number of Email Accounts and domains, the number of sending providers, whether inbound mail needs to be parsed into documents, how many existing mailboxes or aliases must be mapped, and how much access your team can give quickly. Problems inherited from poor DNS, shared sending IPs or undocumented mail flows add diagnosis time. Self-hosting ERPNext is free under its open-source license, so the main costs are the people doing the work and any paid mail provider you choose. Ask for a quote that lists each item in the scope and states what is one-time and what recurs.

Can a partner guarantee that every email will reach the recipient?

No partner can guarantee delivery, because receiving servers make their own filtering decisions and sit outside your control. A well-run setup can make authentication records correct, route bounces to someone who reads them and give your team evidence when a message is rejected. Ask for the steps used to troubleshoot undelivered mail and the records that will be kept, rather than a delivery promise.

What DeployOpen confirms with you before email goes live

Before any ERPNext email setting changes, DeployOpen reviews the account map with you: every Email Account that sends or receives, which role or workflow depends on each one, and which mailbox receives replies and bounces. We then agree the sending domains with you, including the SPF, DKIM and DMARC records your DNS team controls, and the mail provider you will use for outgoing mail. Confirm with your own team who owns each domain, who can change its DNS records, and who will answer when a provider account is suspended. These decisions shape everything after them, so they are settled in writing first.

Next, we agree test cases in writing. A typical set covers a sent invoice or purchase order reaching an external address, a reply from that address being linked back to the right document, a bounced message being visible to the right person, and a scheduled email firing from the scheduler. Each case records the expected result, the test account used and the log you will check, such as the Email Queue and Error Log in the desk. Ask for the same list at handover, so your team can rerun it after a site upgrade or a provider change. Ask your provider which of its own logs and delivery reports you will need access to during testing.

Once testing passes, DeployOpen documents the final configuration: the default outgoing and incoming accounts, the settings for each Email Account, the domains and DNS records, and the runbook for retries and failed deliveries. All work happens inside your infrastructure and under your accounts, and we do not replace your mail provider's support. If the provider blocks your traffic or changes its sending rules, its support team and your own administrators remain the escalation path, and we help you gather the evidence they need. Ask us to show this documentation as part of the written scope before work starts.

How DeployOpen works on this

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and ERPNext email follows the same method. We start from the mail flows your finance, sales and stock processes depend on, then build and test the sending and receiving path in your environment before handing it over.

How we scope

Inventory every email flow ERPNext sends or receives, including invoices, reminders, notifications and auto repeat documents.
Confirm the outgoing and incoming email accounts, sending domains, and the SMTP provider your organization already uses.
Agree the scope in writing before work starts, with deliverables and timelines fixed in the engagement document.

How we build

Configure default incoming and outgoing accounts, domain records and sender identities in your own ERPNext sites.
Test each flow end to end, including delivery to external mailboxes, bounces, and retries after a failed send.
Troubleshoot recipient delivery issues against SPF, DKIM and DMARC records and the provider's logs, with changes recorded.

How we hand over

Document the final email configuration per site, the accounts used, and who owns each DNS and provider setting.
Provide a test checklist your team can rerun after upgrades, certificate changes or provider changes.
Walk your administrators through the Error Log, Scheduled Job Log and outgoing email queue so they can diagnose issues.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer if your email needs change over time.
Review email configuration when you upgrade ERPNext, add sites or change SMTP providers.
Ask any partner, including DeployOpen, to confirm how sender reputation, provider limits and DNS changes are handled in your environment.