Primary Information Sources

<!> Check Gmail service site with keywords like "gmail configuring other mail clients" for new configuration requirement changes.

<!> Please read Debian Exim4 User FAQ first.

PkgExim4UserFAQ is updated by the exim4 maintainer. It should be more current and reliable than this page. "Section 10.1" on PkgExim4UserFAQ mentions problems of this page as of January 2012; this page has been updated since to address these issues, but if you still find errors, please login and correct this page.

This wiki page is only a secondary source of information.

Mail Address Basics

Due to pervasive SPAM problem, most SMTP services including Gmail check the legitimacy of mail messages while delivering them. Email address rewriting as discussed here may cause such SMTP services to filter your mail as illegitimate and drop it quietly. Understanding the difference between the mail envelope address and the mail "From: " address is essential to minimize such risks. Be careful about this problem since the situation changes all the time.

Known Limitations of Gmail

If you send a mail to a mailing list via a SMTP server provided by Gmail, the returned mail message from the mailing list is treated as **read** by the Gmail POP3 service and it may not be downloaded to your local mail client by your mail retrieval or forwarding utility (such as fetchmail/getmail/...). (This is true even if the e-mail address you put in the "To: " field is not your Gmail address but you are forwarding it to the Gmail account you used to send the mail.)

Recently, Gmail started to rewrite both envelope and header addresses to the email address of your account automatically if you use their SMTP smarthost, while also adding a DKIM signature. So there is no point anymore in making complicated mangling of email address if you use Gmail.

If you still wish to have your reply address be some other address forwarded to your Gmail, such as, you need to use a non-Gmail SMTP service such as one provided by the ISP providing IP connectivity to you. Just hope that your ISP does not rewrite the From address as well.

If you are not using two-factor google authentication, LessSecureApps gmail's option must be enabled. Login to your gmail account then go to this url to activate smtp service for your gmail account: . Otherwise this step is not necessary, and won't work anyway.

Using Exim4 to Send Messages through Gmail

<!> Gmail is said to have a limit of 100 messages/day/account when you use it to send mails via its SMTP service. Keep this in mind :)

Debian uses Exim4 as a mail server by default. You can configure this Exim4 to use the Google's SMTP servers as its smarthost using your Gmail account.

Let's assume:

(If you have a real DNS resolvable IP address, the line of /etc/hosts should not exist but should have one for that IP address.)

Initial configuration of Exim4 is invoked with:

# dpkg-reconfigure exim4-config

This setting is for a typical desktop PC which has no resolvable host name. If you wish to do something more such as relaying mail, you need to configure this accordingly.

Submission port 587 on Gmail system uses STARTTLS service to ensure secure password protection.

(For servers with a real DNS resolvable host name, set it accordingly. But there is no good reason to use Gmail as a smarthost if you are in this situation.)

Configuration of Exim4 for SMTP authentication uses the canonical host name.

Gmail provides SMTP under the name . You can get the canonical host names of these servers by running:

$ host is an alias for has address has address

So gmail* matches all the real host names.

The authentication information for the external SMTP service is stored in /etc/exim4/passwd.client. Run

# editor /etc/exim4/passwd.client

and add the following lines:


if you are using two-factor gmail authentication, then do note use :


Here's how /etc/exim4/passwd.client works: the first field in this file is matched against the reverse DNS of the remote SMTP server (in this case Gmail). If this domain name (or IP, if the server IP doesn't have a reverse domain name configured) matches the first field of this file, Exim4 will try to authenticate for SMTP using this login / password.

If you restored /etc/exim4/passwd.client from the backup file, please make sure to restore its file ownership and permissions with

# chown root:Debian-exim /etc/exim4/passwd.client
# chmod 640 /etc/exim4/passwd.client

Edit your address rewrite table /etc/email-addresses by running:

# echo 'YOUR-USER-NAME:' >> /etc/email-addresses
# echo 'YOUR-USER-NAME@localhost:' >> /etc/email-addresses
# echo 'YOUR-USER-NAME@hostname1:' >> /etc/email-addresses
# echo 'YOUR-USER-NAME@hostname1.localdomain:' >> /etc/email-addresses

(Actually, recent Gmail rewrites source address automatically anyway. So you do not need to do the above. But Gmail may change again. This might also be needed for other smarthost settings, so I'll leave it on this page.)

If any message comes to your Exim4 with a different envelope address, you need to list it too.

(Although choosing "YES" for "Hide local mail name in outgoing mail?" may allow you to avoid this trouble, you risk sending unintended mails such as these sent to "root" to the smarthost.)

Finally, run

# update-exim4.conf
# invoke-rc.d exim4 restart
# exim4 -qff

These 3 steps update the Exim4 configuration, reload it, and to force a delivery attempt for all messages including frozen ones.

See "man update-exim4.conf" for more on Exim4 configuration.

Verification of the Configuration and Troubleshooting

After the configuration, please verify your configuration with

# tail /var/log/exim4/mainlog

If you start receiving SMTP authentication errors in mainlog, run

$ host is an alias for has address has address

to verify the resolving host names all match with the definition in your /etc/exim4/passwd.client. Gmail may change its host naming scheme.

If you see in mainlog messages that state something like

failed to open /etc/exim4/passwd.client for linear search:
Permission denied (euid=102 egid=102)

you have some file permission problems. Please restore the default permissions as was mentioned above for backup files. (euid and egid may be different on your installation.)

If you see messages in mainlog that state "Credentials Rejected", the account or password was refused by Gmail. Please check the /etc/exim4/passwd.client file.

Although for most ISP, the account name is simply the part before the arobase, Gmail expects the full e-mail address.

If you see "login authenticator failed" in the mainlog, your account does not have "Less Secure Apps" access enabled. This is the default setting. You'll also receive a notification email from Google that they have blocked this login attempt. You will need to go to this page and "Turn On" the Access for Less Secure Apps setting.

Hint for SMTP service with SSL (but not with STARTTLS)

Deprecated protocol of SSL on port 465 is becoming rare these days. So this is probably not required for you. Try to search an ISP which supports the STARTTLS service on port 587 first.

Even if your only available ISP still does not update its servers to use the standard STARTTLS service on port 587, you can used them safely as smarthost using SMTPS protocol with Exim 4.80 (Debian wheezy and newer). You just need to edit system configuration 30_exim4-config_remote_smtp_smarthost in /etc/exim4/conf.d/transport to add "protocol=smtps". (A bit intrusive change ...)

See under "4. Private options for smtp" on "protocol".

Hints for setting mutt for multiple From: and envelope FROM_ addresses

If you wish to deploy use a different visible e-mail addresses in the "From :" message header field and use different envelope FROM_ address, you need to set it by mail clients generation mail messages such as mutt etc.

Here is an example of .muttrc:

# Explicitly set From_ for ISP
set use_envelope_from
set envelope_from_address="Foo Bar <>"
# Explicitly set From: default
set use_from
set from="Foo Bar <>"

alternates "foo\.bar@gmail\.com|bar\.foo@gmail\.com|foo_bar@example\.com|foobar@debian\.org"
# shortcut for FROM: address change
macro compose "1" "<edit-from>^UFoo Bar \<\>\n"
macro compose "2" "<edit-from>^UFoo Bar \<\>\n"
macro compose "3" "<edit-from>^UFoo Bar \<\>\n"
macro compose "4" "<edit-from>^UFoo Bar \<\>\n"
# short cut for ENVELOPE FROM change
macro compose "5" ":set envelope_from_address=\"Foo Bar \<\>\"\n"
macro compose "8" ":set envelope_from_address=\"Foo Bar \<\>\"\n"