Getting Drupal's mail out of the spam folder
When your Drupal CMS sends emails, for example to deliver module update mails, password resets and so on, and they just won’t arrive as you’d like them to, you can safe yourself a lot of time by checking these items first. Gmail will give you hints where to look but it’s often unclear if you are actually on the right track.
#1 Is the email getting delivered?
Check the mail log of your server, typically /var/log/mail.log or /var/log/mail/something. This should tell you whether the mail gets delivered. If it doesn’t google the error message pertaining to your MTA and go from there.
If that email never arrives, not even in your spam folder, consider using another email account from a different provider to get a copy to start debugging or reduce -all to ~all in your SPF records to get a processed copy, though if you had that set, you will have to wait for the TTL set in your DNS record to time out.
#2 Did you look at the email?
The headers of the email often contain sufficient information to diagnose the problem. Had I done this more thoroughly, I would have found the culprit in no time. For example, there was this:
Received-SPF: none (google.com: email@example.com does not designate permitted sender hosts) client-ip=2600:3c02::ffff:ffff:ffff:ffff;
This means, that Google cannot find my SPF record. This is odd, since I am publishing one. It turns out, that my application settings were incorrect and weren’t able to set the proper from address and thus firstname.lastname@example.org was used instead of email@example.com.
This normally doesn’t happen with sendmail but you can change the behavior either with -f in the sendmail path in php.ini or via this solution.
I would not have run into this problem had myhostname not referenced the www subdomain but in this case I need it to also forward local mail without conflicting with local user accounts.
#3 Is your SPF record OK?
If you still have problems and are publishing an SPF record the headers again should tell you if your SPF record could be found and why it’s not being matched. Most likely, your IP address is missing, so verify with the SPF records checking tools.
Also, be on the lookout for IPv6, if you have it on your machine’s network, even if you are not serving an AAAA record, you need to include such an address, because you might be connecting to it via Google and they want to verify the address they receive content from, e.g.:
Received-SPF: pass (google.com: domain of firstname.lastname@example.org designates 2600:3c02::ffff:ffff:ffff:ffff as permitted sender) client-ip= 2600:3c02::ffff:ffff:ffff:ffff; Authentication-Results: mx.google.com ... )
If that still doesn’t help I’d suggest moving on to burned offerings to the cloud gods.