Short answer: When Docassemble email doesn’t send, the cause is usually a missing or incomplete mail section in the Configuration (no default sender, wrong SMTP server, port or TLS settings), SMTP traffic being slowed or blocked by your host, or code that ignores the return value of send_email(). Set a default sender, move to an HTTP API such as Mailgun or SendGrid, and check what send_email() returns.
Email powers password resets, multi-user interview notifications and the delivery of finished documents, so it matters for legal aid, court-form and law-firm projects in the USA, UK and Australia alike. This guide uses a symptom → cause → fix format, based on the official docassemble e-mail configuration docs, the send_email() reference and the e-mailing the interview section.
Note: the code and configuration below are examples based on the official docassemble documentation. Test them on a staging server before using them in production, and never paste real API keys or passwords into shared files.
Quick diagnostic table
| Symptom | Likely cause | Fix |
|---|---|---|
| No email is sent at all, including password resets | No sending service configured under mail | Add an SMTP server or an HTTP API (Mailgun, SendGrid, Microsoft Graph) |
| Wrong or odd “From” address | default sender not set | Set default sender under mail |
| Can’t reset the admin password | Admin still uses the default fake address | Change the admin user’s email to a real inbox |
| Sending is slow or times out in the cloud | SMTP is slow, and hosts may throttle or block it | Use the Mailgun or SendGrid API over HTTP |
| Mailgun API fails on an EU account | EU domains use a different base URL | Set mailgun api url to the api.eu.mailgun.net URL |
send_email() returns False | An error stopped delivery to the mail server | Check the configuration and the Logs |
send_email() returns True but nothing arrives | True only means the hand-off worked | Check the provider’s logs and the recipient’s spam folder |
| User stares at a spinner while email sends | Sending inside interview logic | Send from a background process |
| Attachment missing | Wrong object type passed | Pass DAFile, DAFileList or DAFileCollection objects in a list |
| Email-to-interview receives nothing | Server not set up to receive mail | Ports 25/465, MX record, firewall, incoming mail domain |
Why isn’t Docassemble sending any email?
Answer: Docassemble needs an email sending service before it can send anything. The docs say you can use an external SMTP server or a provider with an HTTP API, and recommend the API option because SMTP is slow. Add a mail section to the Configuration (Menu → Configuration) with at least a default sender, which sets the return address on every email the server generates.
Before you start, make sure the administrator account isn’t still using the default fake email address. If it is, the “forgot my password” feature can’t help you get back in.
SMTP example
mail:
default sender: '"Administrator" <no-reply@example.com>'
username: mailuser
password: abc123
server: smtp.example.com
port: 25
use ssl: False
use tls: True
Check each value against your provider’s SMTP details: server name, port, and whether it expects SSL or TLS. If you host Docassemble in the cloud, the docs note you will probably need a separate SMTP server to send email at all.
Should I use SMTP or an email API with Docassemble?
Answer: Prefer an HTTP API. The docs explain that the Mailgun API may be more reliable than SMTP because internet service providers may slow down or block SMTP traffic to fight spam. Docassemble supports the Mailgun API, the SendGrid API and the Microsoft Graph API on Azure.
Mailgun API
mail:
default sender: '"Example, Inc." <no-reply@mg.example.com>'
mailgun api key: YOUR-MAILGUN-API-KEY
mailgun domain: mg.example.com
The default API URL is https://api.mailgun.net/v3/%s/messages.mime, with your mailgun domain substituted for %s. Mailgun domains created in the EU region need a different base URL. This matters for UK and EU-hosted projects:
mail:
mailgun api url: https://api.eu.mailgun.net/v3/%s/messages.mime
SendGrid API
mail:
default sender: '"Example, Inc." <no-reply@example.com>'
sendgrid api key: YOUR-SENDGRID-API-KEY
Microsoft 365 (Graph API on Azure)
Firms on Microsoft 365 can register an app in the Azure Portal, grant it the Microsoft Graph application permission Mail.Send with admin consent, create a client secret, and then set azure client id, azure tenant id and azure client secret under mail. The docs warn that you can only send from senders whose mailboxes the app registration has access to. That is a common reason for Graph sends failing.
Why does send_email() return True but the email never arrives?
Answer: send_email() returns False only if an error stopped the email being handed to the mail server. Otherwise it returns True. The docs say it might return True even though nothing is actually delivered, because the return value only shows whether Flask-Mail hit a problem. After a True, check your provider’s sending logs and the recipient’s spam folder.
code: |
email_sent_ok = send_email(to=recipient, template=notification)
---
template: notification
subject: |
Your documents are ready, ${ recipient }
content: |
Your documents have been prepared. Please review them carefully.
Always store and check the return value, and show the user a clear message when it is False. Docassemble’s Logs (and docassemble.log) are the next place to look.
Check variables before sending with dry_run
Setting dry_run=True runs the sending process without sending, which confirms that every variable send_email() needs is defined first.
Why is my interview slow when it sends email?
Answer: Sending email can be slow. If you call send_email() inside your interview logic, the user may be left looking at a spinner. The docs suggest calling it from a background process instead.
Why are my email attachments missing?
Answer: attachments expects a list of DAFile, DAFileList or DAFileCollection objects. That covers signature images, files uploaded through datatype: file or datatype: files, and documents generated by an attachment that has a variable name. Passing a filename string, or a single object without wrapping it in a list, is a common mistake.
code: |
success_sending_email = send_email(
to=[user],
template=hello_email,
attachments=[the_file])
If the generated document itself is wrong, see our guides to DOCX template errors and PDF fields not filling.
Why does the wrong recipient, sender or reply-to appear?
Answer: to takes Individuals, Persons, DAEmailRecipients or plain addresses, either as a list or as a single item. When you pass Individual objects, the address is built from their name and email attributes, so an undefined email attribute will trigger a question or an error. sender takes a single Individual; if you leave it out, the configured default sender is used. Use reply_to to direct replies to a caseworker or fee earner, and cc and bcc for copies.
How do I send from different accounts in different interviews?
Answer: Make mail a list of named configurations, then choose one with email config in an interview’s metadata, or with config= in send_email().
mail:
- name: abc
default sender: '"ABC, Inc." <no-reply@abc.example.com>'
sendgrid api key: YOUR-SENDGRID-API-KEY
- name: def
default sender: '"DEF, Inc." <no-reply@def.example.com>'
mailgun api key: YOUR-MAILGUN-API-KEY
mailgun domain: mg.def.example.com
metadata:
email config: def
Watch out: system emails such as invitations, error notifications and forgot-password emails are sent outside any interview. They use the configuration named default, or the first configuration in the list if none is named default. If password resets go out from the wrong account, this is why.
Why don’t I get error notification emails?
Answer: Set error notification email to one or more addresses, and the server will try to email them whenever a user sees an error. This relies on working outgoing mail, so fix sending first. Use suppress error notificiations (that is the directive’s spelling in the docs) to silence error classes you don’t care about, such as ReadTimeout.
Why isn’t email-to-interview receiving anything?
Answer: interview_email() gives each session a unique address, and get_emails() reads what arrives, but only if the server is set up to receive mail. With Docker, the docs list these requirements:
- Stop any mail server already running on the Docker host. Many Linux distributions run one on port 25.
- Start the container with
-p 25:25 -p 465:465. - Point your domain’s MX record at the server, or at the machine with the
mailcontainer role in a multi-server setup. - Allow incoming connections on ports 25 and/or 465 in your firewall or cloud security groups.
- Set
incoming mail domain, unless you are using the same domain asexternal hostname.
Also check that enable email server hasn’t been set to False. That setting disables the Exim4-based receiving feature.
Processing email in the background
To act on an email when the user isn’t online, handle an incoming_email action and save results with background_response_action(). The interview must set multi_user = True, because the server can’t decrypt the session without the user’s password. Changes to variables must go through a separate action called with background_response_action().
event: incoming_email
code: |
background_response_action('save_email', email=action_argument('email'))
---
event: save_email
code: |
email = action_argument('email')
background_response()
Port and container problems often show up after upgrades. See Docassemble Docker upgrade and deployment problems.
FAQ
What is the minimum email configuration Docassemble needs?
A mail section with a default sender and one sending method: SMTP credentials, a Mailgun API key and domain, a SendGrid API key, or Azure Graph credentials.
Is Mailgun or SendGrid better than SMTP for Docassemble?
The docs recommend an HTTP API because SMTP is slow and may be throttled or blocked by hosting providers. Both Mailgun and SendGrid APIs are supported.
Does send_email() returning True mean the email was delivered?
No. It only means no error stopped the hand-off to the mail server. Confirm delivery in your provider’s logs.
How do I attach a generated document to an email?
Give the attachment a variable name, then pass that DAFileCollection in a list: attachments=[my_document].
How do users email documents into an interview?
Show them the address from interview_email() and read submissions with get_emails(). The server must accept mail on ports 25/465 and have an MX record pointing at it.
Need a hand?
If emails, notifications or client document delivery are unreliable on your Docassemble server, our Docassemble maintenance and support team can help. You can also book a free Docassemble audit to check your configuration, email delivery and interviews.
Sources: docassemble documentation, Configuration: E-mail configuration, Functions: send_email(), interview_email(), get_emails(), Background processes: E-mailing the interview, Docker. Checked 3 Nov 2026.
More in this Docassemble troubleshooting series – Docassemble DOCX template errors: causes and fixes – Docassemble PDF fields not filling: causes and fixes – Docassemble Docker upgrade and deployment problems – Docassemble support and maintenance