Nextcloud Email Setup: Why Password Reset Emails Never Arrive (and How to Fix It)
Nextcloud has no mail server of its own, so password resets and notifications go nowhere until you enter your mail provider's SMTP details under Administration settings, Basic settings, Email server. The login page says the reset was sent either way. Put an email address on your own account so the test can reach you, and when the test fails, read Administration settings, Logging.
Nextcloud's "Forgot password?" page says a reset message "has been sent to its email address" even when nothing was sent. On a fresh install nothing ever is: Nextcloud has no mail server of its own. The fix is to give it the SMTP details of a mail account you already have, under Administration settings → Basic settings → Email server.
We filmed every step on a fresh Nextcloud 35.0.1 in Docker. For the video,
Nextcloud sent its mail to a test mailbox on our own network, so the server name
you see on screen (smtp.home.arpa) is a stand-in for your provider's.
Why does Nextcloud say the reset email was sent when it wasn't?
The message is deliberately vague: "If this account exists, a password reset message has been sent to its email address." It reads the same whether the mail went out or not (and whether the account exists or not, which keeps the page from revealing who has an account). On our fresh install it appeared, and the mailbox stayed empty. Nextcloud's own log recorded what really happened: "Could not send password reset email: Could not send reset e-mail since there is no email for username admin".
Two things have to be true for a reset to arrive:
- Nextcloud has a mail server to send through (the Email server settings).
- The account asking for the reset has an email address on it. Each person sets theirs in Personal settings → Personal info, or an admin sets it in Accounts.
The admin manual says it directly: "Nextcloud does not contain a full email server, but rather connects to your existing mail server."
What do I need from my mail provider?
Look for your provider's SMTP settings (sometimes called "outgoing mail" or "send mail from an app or device"). You need:
- The server name, for example
smtp.gmail.com. - A port, which decides the encryption setting in Nextcloud:
port
587goes with None / STARTTLS (Nextcloud starts plain and upgrades to encryption when the server offers it), and port465goes with SSL/TLS. - A login and password. The login is usually your full email address.
Gmail and Google Workspace: Google's setup page gives the
server as smtp.gmail.com, "For SSL, enter 465. For TLS, enter 587",
your complete email address as the login, and an app password, not your
normal password. Google's help adds: "App passwords can only be used with accounts
that have 2-Step Verification turned on." Google also notes a sending limit of
2,000 messages per day on this server, far more than a home Nextcloud sends.
How do I set up the Email server in Nextcloud?
- Sign in as an admin and open Administration settings → Basic settings. Scroll to Email server.
- Send mode: SMTP. In the Docker image it's the only choice,
because the image has no
sendmail. - Encryption: None / STARTTLS for port 587, SSL/TLS for port 465. Leave "Disable certificate verification (insecure)" off.
- From address: the name before the @ and the domain after it. Use an address your mail account is allowed to send as.
- Server address: your provider's host and port.
- Authentication: turn on "Authentication required", then enter the login and password.
- Click Save settings. Nextcloud shows no confirmation when the save works; it has saved.
- Click Send test email.
Why does Send test email say "You need to set your account email"?
The test mail goes to you, the admin who clicked the button, so your own account needs an email address first. The full message is "You need to set your account email before being able to send test emails." Add your address under Personal settings → Personal info → Email (it saves on its own), then go back and press the button again. The manual gives the same order: "save your email address in your personal settings and then use the Send email button".
The test says "Check your mail server log". Where is the real error?
When sending fails, the page only says: "A problem occurred while sending the email. Please revise your settings. (Error: Email could not be sent. Check your mail server log)". The reason is in Nextcloud's own log, at Administration settings → Logging. Open the newest red row with the arrow at its end to see the whole message.
In our test we chose SSL/TLS on port 587. The log said:
Connection could not be established with host "ssl://smtp.home.arpa:587":
stream_socket_client(): SSL operation failed with code 1.
OpenSSL Error messages: error:0A00010B:SSL routines::wrong version numberThe ssl:// at the start means Nextcloud tried to begin an encrypted
connection immediately, on a port that expects to start plain and upgrade with
STARTTLS. Switching Encryption to None / STARTTLS fixed it: "Email sent
successfully", and the test mail arrived. If Logging is missing from your menu, the
same lines are in nextcloud.log in your data folder.
Other errors you may see there come from your provider, not Nextcloud: a wrong
host name means the connection is never made, and a wrong password is refused by the
provider's server. If you need more detail, the manual's troubleshooting section
describes turning on mail_smtpdebug while you test.
How do I set Nextcloud's mail settings in Docker?
The official image can take the same settings as environment variables. In our
test with nextcloud:35.0.1-apache two things mattered:
- They only count as a set. The image reads them only when
SMTP_HOST,MAIL_FROM_ADDRESSandMAIL_DOMAINare all present. WithSMTP_HOST,SMTP_PORT,SMTP_NAMEandSMTP_PASSWORDset but the twoMAIL_variables left out, Nextcloud had no mail server at all and the test failed. - Once set, they win over the form. The image loads them from
its own config file on every request, after
config.php. When we changed the host inconfig.phpto a server that doesn't exist, the test still went out through the variables. Use the variables or the form, not both.
environment:
- SMTP_HOST=smtp.gmail.com
- SMTP_SECURE=ssl # empty for port 587 (STARTTLS), ssl for 465
- SMTP_PORT=465
- SMTP_NAME=you@gmail.com
- SMTP_PASSWORD=your-app-password
- MAIL_FROM_ADDRESS=you # the part before the @
- MAIL_DOMAIN=gmail.com # the part after the @Unlike NEXTCLOUD_TRUSTED_DOMAINS, which the image only reads at
the first install (see our untrusted domain
guide), the mail variables apply every time the container starts with them.
Should I run my own mail server for Nextcloud?
Usually not. It's a much bigger job than Nextcloud itself, and mail sent from a home internet connection is often refused or sent to spam by the big providers. An existing mailbox at your provider, or a transactional sending service, is the simpler route. If your resets do arrive but land in spam, the fix is with the domain you send from (its SPF and DKIM records at your provider), not in Nextcloud.
Is this the Nextcloud Mail app?
No. The Mail app is an email client inside Nextcloud for reading your own mail. It doesn't make password resets work. The "Mail Providers" setting further down Basic settings uses it only for calendar invitations, per its own description. The Email server section is what the server uses for its own messages.
Sources
Full video transcript
1
00:00:00,000 --> 00:00:04,359
If your Nextcloud password reset
emails never arrive, here's why.
2
00:00:04,399 --> 00:00:07,066
Nextcloud has no mail server of its own.
3
00:00:07,106 --> 00:00:12,683
Until you connect it to one, under Basic
settings, Email server, nothing gets sent,
4
00:00:12,723 --> 00:00:14,781
even when the page says it was.
5
00:00:14,821 --> 00:00:18,638
I'll set it up, show you the
two places people get stuck,
6
00:00:18,678 --> 00:00:21,925
and where Nextcloud writes
down the real reason.
7
00:00:22,325 --> 00:00:25,615
This is Nextcloud thirty
five, freshly installed.
8
00:00:25,655 --> 00:00:29,013
It runs in Docker, on a
Linux server I run myself.
9
00:00:29,053 --> 00:00:34,177
Let's see what happens when someone
forgets their password. Forgot password.
10
00:00:34,217 --> 00:00:36,459
The login, admin. Reset password.
11
00:00:37,712 --> 00:00:40,252
Nextcloud says: if this account exists,
12
00:00:40,292 --> 00:00:44,221
a password reset message has
been sent to its email address.
13
00:00:44,261 --> 00:00:47,371
The account exists. So
let's check the mailbox.
14
00:00:48,623 --> 00:00:53,410
For this video, Nextcloud's mail goes
to a test mailbox on my own network,
15
00:00:53,450 --> 00:00:55,276
so nothing leaves the house.
16
00:00:56,487 --> 00:00:58,217
It's empty. Nothing was sent.
17
00:00:58,257 --> 00:01:02,489
And nothing ever will be, until you
give Nextcloud a way to send mail.
18
00:01:02,529 --> 00:01:04,054
That's the whole problem.
19
00:01:05,295 --> 00:01:09,862
Nextcloud's admin manual explains
why, on its page about email.
20
00:01:11,072 --> 00:01:13,731
Nextcloud does not contain
a full email server,
21
00:01:13,771 --> 00:01:16,585
but rather connects to
your existing mail server.
22
00:01:17,814 --> 00:01:20,989
In plain words, Nextcloud
doesn't send mail by itself.
23
00:01:21,029 --> 00:01:24,383
It hands each message to a
mail account you already have,
24
00:01:24,423 --> 00:01:26,705
the way a printer's scan to email does.
25
00:01:26,745 --> 00:01:29,086
You give it that account's details once.
26
00:01:29,126 --> 00:01:32,698
Then every reset and every share
notice goes out through it.
27
00:01:33,974 --> 00:01:39,529
Those details come from your mail
provider. Look for their SMTP settings.
28
00:01:39,569 --> 00:01:45,661
You need the server's name, and a port.
The port decides the encryption setting.
29
00:01:45,701 --> 00:01:48,727
Port 587 goes with None, slash STARTTLS.
30
00:01:48,767 --> 00:01:54,782
The other common port, 465, goes with
SSL slash TLS. Then a login and password.
31
00:01:54,822 --> 00:02:00,914
For Gmail, the server is smtp.gmail.com,
and the password isn't your normal one.
32
00:02:00,954 --> 00:02:07,391
It's an app password, and Google only offers
those once two-step verification is on.
33
00:02:08,751 --> 00:02:11,685
To fix it, I'll sign in as the admin.
34
00:02:15,043 --> 00:02:19,344
The setting is in Administration
settings, under Basic settings.
35
00:02:20,941 --> 00:02:23,164
Here's the Email server section.
36
00:02:23,204 --> 00:02:28,255
It says it plainly: you need this for
password resets and notifications.
37
00:02:28,295 --> 00:02:32,820
Send mode is SMTP. On this Docker
install, it's the only choice.
38
00:02:34,076 --> 00:02:37,741
Now the encryption. My test
mail server uses port 587.
39
00:02:37,781 --> 00:02:42,818
But I'll pick SSL slash TLS anyway,
because it sounds like the secure one.
40
00:02:42,858 --> 00:02:47,111
It's an easy mix-up, and I want
you to see what it looks like.
41
00:02:48,319 --> 00:02:52,968
The from address is who the mail says
it's from. The part before the at sign,
42
00:02:54,185 --> 00:02:59,336
and the domain after it. Use an address
your mail account is allowed to send as.
43
00:03:00,556 --> 00:03:05,629
The server's name, from your provider.
Mine is the test server on my network.
44
00:03:06,847 --> 00:03:09,983
And the port. 587.
45
00:03:11,197 --> 00:03:16,325
Most providers want you to sign in.
Turn on Authentication required.
46
00:03:17,545 --> 00:03:20,228
The login is usually
your full email address.
47
00:03:21,872 --> 00:03:25,969
And the password. For Gmail,
that's the app password.
48
00:03:27,184 --> 00:03:32,718
Save settings. Nextcloud doesn't say
anything when the save works. It did save.
49
00:03:33,935 --> 00:03:38,915
Now the button that tells you
if it works. Send test email.
50
00:03:40,120 --> 00:03:44,824
You need to set your account email
before being able to send test emails.
51
00:03:44,864 --> 00:03:47,229
The test mail goes to you, the admin.
52
00:03:47,269 --> 00:03:50,388
And this admin account
has no email address yet.
53
00:03:51,644 --> 00:03:55,693
So, your own settings. Personal info.
54
00:03:57,704 --> 00:04:00,823
Add your email address.
It saves on its own.
55
00:04:04,489 --> 00:04:08,117
This is also where your own
password resets will go.
56
00:04:08,157 --> 00:04:11,332
Keep that in mind, it
comes back in a minute.
57
00:04:12,569 --> 00:04:14,342
Back to Basic settings.
58
00:04:18,654 --> 00:04:20,200
And send the test again.
59
00:04:21,967 --> 00:04:26,286
A problem occurred while sending the
email. Please revise your settings.
60
00:04:26,326 --> 00:04:30,928
Check your mail server log. That's all
it says. It doesn't say what's wrong.
61
00:04:32,171 --> 00:04:38,854
The reason is in Nextcloud's own log.
Administration settings, Logging.
62
00:04:40,066 --> 00:04:43,701
Connection could not be
established with host.
63
00:04:43,741 --> 00:04:49,814
And look at the start of the address:
S S L, then the server, then port 587.
64
00:04:51,053 --> 00:04:56,000
There's the reason. Nextcloud tried to
start an encrypted connection straight away.
65
00:04:56,040 --> 00:04:59,485
But this port expects the
connection to begin unencrypted,
66
00:04:59,525 --> 00:05:01,348
and switch to encryption after.
67
00:05:01,388 --> 00:05:04,092
The two never agree, so
nothing gets through.
68
00:05:05,351 --> 00:05:09,664
And further down, this is the
reset from the start of the video.
69
00:05:09,704 --> 00:05:14,534
Could not send reset email, since
there is no email for username admin.
70
00:05:15,775 --> 00:05:17,829
So that reset never had a chance.
71
00:05:17,869 --> 00:05:21,129
There was no mail server,
and no address to send to.
72
00:05:21,169 --> 00:05:25,444
Every account needs its own email
address, or its resets go nowhere.
73
00:05:25,484 --> 00:05:29,736
The login page says sent either
way. The log is where you find out.
74
00:05:31,000 --> 00:05:33,984
Back to Basic settings,
to fix the encryption.
75
00:05:36,892 --> 00:05:39,601
Port 587, so None slash STARTTLS.
76
00:05:39,641 --> 00:05:46,387
Nextcloud begins unencrypted, and switches
to encryption if the server offers it.
77
00:05:47,617 --> 00:05:48,263
Save.
78
00:05:52,284 --> 00:05:54,190
Send test email.
79
00:05:55,543 --> 00:05:57,381
Email sent successfully.
80
00:05:58,596 --> 00:05:59,977
And in the mailbox,
81
00:06:02,039 --> 00:06:07,273
there it is. Email setting test, from
Nextcloud, to the admin's address.
82
00:06:08,504 --> 00:06:13,218
Now the real test. Sign out,
and ask for a reset again.
83
00:06:14,437 --> 00:06:19,984
Forgot password. The login. Reset
password. The same message as before.
84
00:06:21,202 --> 00:06:22,463
Back to the mailbox.
85
00:06:24,559 --> 00:06:26,430
This time, it's there.
86
00:06:27,642 --> 00:06:33,323
Nextcloud password reset. From the address
we set, to the address on the account.
87
00:06:34,547 --> 00:06:37,590
Inside, a button to reset the password.
88
00:06:38,804 --> 00:06:43,477
And it opens Nextcloud's page for
choosing a new password. The reset works.
89
00:06:44,703 --> 00:06:47,784
One more thing, if you
run the Docker image.
90
00:06:47,824 --> 00:06:53,742
You can set all of this with environment
variables instead, starting with SMTP host.
91
00:06:53,782 --> 00:06:55,302
There are two catches.
92
00:06:55,342 --> 00:07:00,621
The image only reads them if mail from
address and mail domain are set too.
93
00:07:00,661 --> 00:07:03,813
Leave either out, and
it ignores all of them.
94
00:07:03,853 --> 00:07:07,927
And once they're set, they win
over this form, every time.
95
00:07:07,967 --> 00:07:13,143
Change the form, and nothing changes.
So pick one place, and stick to it.
96
00:07:15,094 --> 00:07:17,833
So. Nextcloud has no
mail server of its own.
97
00:07:17,873 --> 00:07:22,065
Give it your provider's details
under Basic settings, Email server.
98
00:07:22,105 --> 00:07:26,360
Put an email address on your own
account, so the test can reach you,
99
00:07:26,400 --> 00:07:29,203
and on every account
that might need a reset.
100
00:07:29,243 --> 00:07:32,298
When the test fails, the
reason is under Logging.
101
00:07:32,338 --> 00:07:35,772
And in Docker, use the form
or the variables, not both.
102
00:07:35,812 --> 00:07:40,361
The settings for Gmail and other
providers are on the page linked below.