Skip to content

Email guide

Note

If you're looking for advanced documentation on how to operate this service, head over to the service documentation.

Configuration

In general, you can configure your email client with the following SMTP settings:

  • Description: torproject.org
  • Server name: submission.torproject.org
  • Port: 465
  • Connection security: TLS
  • Authentication method: Normal password
  • User Name: your LDAP username without the @torproject.org part, e.g. in my case it is anarcat
  • Password: LDAP email password set on the LDAP dashboard

If your client fails to connect in the above configuration, try STARTTLS security on port 587 which is often open when port 465 is blocked.

Setting an email password

To use the email submission service, you first need to set a "mail password". For this, you need to update your account in LDAP:

  1. head towards https://db.torproject.org/update.cgi
  2. login with your LDAP credentials (here's how to do a password reset if you lost that)
  3. be careful to hit the "Update my info" button (not the "Full search")
  4. enter a new, strong password in the Change mail password: field (and save it in your password manager) Email password field within the form
  5. hit the Update... button

What this will do is set a "mail password" in your LDAP account. Within a few minutes, this should propagate to the submission server, which will then be available to relay your mail to the world. Then the next step is to configure your email client, below.

Thunderbird configuration

In Thunderbird, you will need to add a new SMTP account in "Account", "Account settings", "Outgoing Server (SMTP)". Then click "Add" and fill the form with:

  • Server name: submission.torproject.org
  • Port: 465
  • Connection security: SSL/TLS
  • Authentication method: Normal password
  • User Name: (your LDAP username, e.g. in my case it is anarcat, without the @torproject.org part)

If your client fails to connect in the above configuration, try STARTTLS security on port 587 which is often open when port 465 is blocked.

Then you can set that account as the default by hitting the "Set default" button, if only your torproject.org identity is configured on the server.

If not, you need to pick your torproject.org account from the "Account settings" page, then at the bottom pick the tor SMTP server you have just configured.

Then on first email send you will be prompted for your email password. This password usually differs from the one used for logging in to db.torproject.org. See how to set the email password. You should NOT get a certificate warning, a real cert (signed by Let's Encrypt) should be presented by the server.

Use torproject.org identity when replying

In most cases Thunderbird will select the correct identity when replying to messages that are addressed to your "@torproject.org" address. But in some other cases such as the Tor Project mailing lists, where the recipient address is not yours but the mailing list, replying to a list message may cause a warning to appear in the bottom of the compose window: "A unique identity matching the From address was not found. The message will be sent using the current From field and settings from identity username@torproject.org."

This problem can be fixed by going into "Account settings", "Manage identities", clicking "Edit..." after selecting the torproject.org identity. In the dialog shown, check the box next to "Reply from this identity when delivery headers match" and in the input field, enter "torproject.org".

Apple Mail configuration

These instructions are known to be good for OSX 14 (Sonoma). Earlier versions of Apple Mail may not expose the same settings.

Before configuring the outgoing SMTP server, you need to have an existing email account configured and working, which the steps below assume is the case.

  1. Open the Mail menu, go into Settings dialog and the Accounts tab, and not the Accounts menu from the Mail menu

  2. On the left-hand side, select the account to associate with your @torproject.org address

  3. Add your @torproject.org address in the "Email Addresses" drop down

  4. Open the "Server Settings" tab

  5. Click the "Outgoing Mail Account" drop-down menu and select "Edit SMTP Server List"

  6. Click the "+" sign to create a new entry:

    • Description: Tor Project Submission
    • User Name: (your LDAP username, e.g. in my case it is anarcat, without the @torproject.org part)
    • Password: the correct one.
    • Host Name: submission.torproject.org
    • Automatically manage connection settings: unchecked, which will pop open the following settings:
      • Port: 587 (default)
      • Use TLS/SSL: checked (default)
      • Authentication: Password
    1. Click OK, close the "Accounts" dialog

    2. Send a test email, ensuring to select your @torproject.org address is selected in the From: field

Gmail configuration

Follow those steps to configure an existing Gmail account to send email through the Tor Project servers, to be able to send email with a @torproject.org identity.

  1. Log in to your Gmail account in a web browser

  2. Click on "Settings", that should be the big gear icon towards the top right of your window

  3. A "quick settings" menu should open. Click on the "See all settings" button at the top of that menu.

  4. This will take you to a "Settings" page. Click on the "Accounts and Import" tab at the top of the page.

  5. Under "Send mail as", click "Add another email address" and add the yourname@torproject.org address there. Keep the "treat as an alias" box checked.

    If this fails with an error like:

      Functionality not enabled.
      You must send through torproject.org SMTP servers when you send as esraa@torproject.org. However, this functionality is not available for your account. Please contact your domain administrator for more information.
    

    That is because the functionality is, well, not enabled. A Google Workspace administrator need to to "Allow per-user outbound gateways" first.

  6. Click the "edit info" link to the right of that account

  7. A new "Edit email address" popup should open. Click "Next step" on it.

  8. Finally, you'll be at a window that says "Edit email address". Fill it out like this:

    • Select "Send through torproject.org SMTP servers".
    • Set "SMTP Server:" to submission.torproject.org, not mx-dal-01.torproject.org
    • Set "Port:" to 465.
    • Set "Username:" to your username (without @torproject.org).
    • Set "Password:" to the email submission password that you configured.
    • Keep "Secured connection using SSL (recommended)" selected, the other one "Secured connection using TLS"

    Double-check everything, then click "Save Changes". Gmail will try authenticating to the SMTP server; if it's successful, then the popup window will close and your account will be updated.

  9. A confirmation email will be sent to the yourname@torproject.org which should forward back to your Gmail mailbox.

  10. Try sending a mail with your @torproject.org identity.

    When you compose a new message, on the "From" line, there will now be a drop-down menu, where you can pick your normal Gmail account or the new @torproject.org account as your identity.

    It might take a while to propagate.

Glossary

  • SMTP: Simple Mail Transfer Protocol. The email protocol spoken between servers to deliver email. Consists of two standards, RFC821 and RFC5321 which defined SMTP extensions, also known as ESMTP.
  • MTA: Mail Transport Agent. A generic SMTP server. mta-dal-01 is such a server.
  • MUA: Mail User Agent. An "email client", a program used to receive, manage and send email for users.
  • MSA : Mail Submission Agent. An SMTP server specifically designed to only receive email.
  • MDA: Mail Delivery Agent. The email service actually writing the email to the user's mailbox. Out of scope.

This document describes the implementation of a MSA, although the service will most likely also include a MTA functionality in that it will actually deliver emails to targets.

More obscure clients configuration

This section regroups email client configurations that might be a little more exotic than commonly used software. The rule of thumb here is that if there's a GUI to configure things, then it's not obscure.

Also, if you know what an MTA is and are passionate about standards, you're in the obscure category, and are welcomed to this dark corner of the internet.

msmtp configuration

"msmtp is an SMTP client" which "transmits a mail to an SMTP server which takes care of further delivery". It is particularly interesting because it supports SOCKS proxies, so you can use it to send email over Tor.

This is how dgoulet configured his client:

# Defaults for all accounts.
defaults
auth on
protocol smtp
tls on
port 465

# Account: dgoulet@torproject.org
account torproject
host submission.torproject.org
from dgoulet@torproject.org
user dgoulet
passwordeval pass mail/dgoulet@torproject.org

Postfix client configuration

If you run Postfix as your local Mail Transport Agent (MTA), you'll need to do something special to route your emails through the submission server.

First, set the following configuration in main.cf, by running the following commands:

postconf -e smtp_sasl_auth_enable=yes
postconf -e smtp_sasl_password_maps=hash:/etc/postfix/sasl/passwd
postconf -e smtp_sasl_security_options=
postconf -e relayhost=[submission.torproject.org]:submission
postconf -e smtp_tls_security_level=secure
postconf -e smtp_tls_CAfile=/etc/ssl/certs/ca-certificates.crt
postfix reload

The /etc/postfix/sasl/passwd file holds hostname user:pass configurations, one per line:

touch /etc/postfix/sasl/passwd
chown root:root /etc/postfix/sasl/passwd && chmod 600 /etc/postfix/sasl/passwd
 echo "submission.torproject.org user:pass" >> /etc/postfix/sasl/passwd

Then rehash that map:

postmap /etc/postfix/sasl/passwd

Note that this method stores your plain text password on disk. Make sure permissions on the file are limited and that you use full disk encryption.

You might already have another security_level configured for other reasons, especially if that host already delivers mail to the internet at large (for example: dane or may). In that case, do make sure that mails are encrypted when talking to the relayhost, for example through a smtp_tls_policy_maps (see below). You want at least the verify (if you trust DNS to return the right MX records) or secure (if you don't). dane can work (for now) because we do support DNSSEC, but that might change in the future.

If you want to use Tor's submission server only for mail sent from a @torproject.org address, you'll need an extra step. This should be in main.cf:

postconf -e smtp_sender_dependent_authentication=yes
postconf -e sender_dependent_relayhost_maps=hash:/etc/postfix/sender_relay

Then in the /etc/postfix/sender_relay file:

# Per-sender provider; see also /etc/postfix/sasl_passwd.
anarcat@torproject.org               [submission.torproject.org]:submission

Then rehash that map as well:

postmap /etc/postfix/sender_relay

If you are setting smtp_sender_dependent_authentication, do not set the relayhost (above).

If you have changed your default_transport, you'll also need a sender_dependent_default_transport_maps as well:

postconf -e sender_dependent_default_transport_maps=hash:/etc/postfix/sender_transport

With /etc/postfix/sender_transport looking like:

anarcat@torproject.org               smtp:

Hash that file:

postmap /etc/postfix/sender_transport

For debugging, you can make SMTP client sessions verbose in Postfix:

smtp      unix  -       -       -       -       -       smtp -v

To use a tls_policy_map for just the mails you're delivering via Tor's mail server (assuming you want to use security level dane-only, otherwise change it to verify or secure as described above), put the below into /etc/postfix/tls_policy:

submission.torproject.org:submission    dane-only

Hash that file as well and use it in your config:

postmap /etc/postfix/tls_policy
postconf -e smtp_tls_policy_maps=hash:/etc/postfix/tls_policy

smtp_sasl_mechanism_filter is also very handy for debugging. For example, you can try to force the authentication mechanism to cram-md5 this way.

If you can't send mail after this configuration and get an error like this in your logs:

Sep 26 11:54:19 angela postfix/smtp[220243]: warning: SASL authentication failure: No worthy mechs found

Try installing the libsasl2-modules Debian package.

Exim4 client configuration

You can configure your Exim to send mails which you send From: your torproject.org email via the TPI submission service, while leaving your other emails going whichever way they normally do.

These instructions assume you are using Debian (or a derivative), and have the Debian semi-automatic exim4 configuration system enabled, and have selected "split configuration into small files". (If you have done something else, then hopefully you are enough of an Exim expert to know where the pieces need to go.)

  1. Create /etc/exim4/conf.d/router/190_local_torproject containing
smarthost_torproject:
  debug_print = "R: Tor Project smarthost"
  domains = ! +local_domains
  driver = manualroute
  transport = smtp_torproject
  route_list = * submission.torproject.org
  same_domain_copy_routing = yes
  condition = ${if match{$h_From:}{torproject\.org}{true}{false}}
  no_more
  1. Create /etc/exim4/conf.d/transport/60_local_torproject containing (substituting your TPI username):
smtp_torproject:
  driver = smtp
  port = 465
  return_path = USERNAME@torproject.org
  hosts_require_auth = *
  hosts_require_tls = *
  1. In /etc/exim4/passwd.client add a line like this (substituting your TPI username and password):
*.torproject.org:USERNAME:PASSWORD
  1. Run update-exim4.conf (as root).

  2. Send a test email. Either examine the Received lines to see where it went, or look at your local /var/log/exim4/mainlog, which will hopefully say something like this:

2022-07-21 19:17:37 1oEajx-0006gm-1r => ...@torproject.org R=smarthost_torproject T=smtp_torproject H=submit-01.torproject.org [2a01:4f8:fff0:4f:266:37ff:fe18:2abe] X=TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256 CV=yes DN="CN=submit-01.torproject.org" A=plain K C="250 2.0.0 Ok: 394 bytes queued as C3BC3801F9"

By default authentication failures are treated as temporary failures. You can use exim -M ... to retry messages. While debugging, don't forget to update-exim4.conf after making changes.

How to report email problems

Email delivery problems are unfortunately quite common but there are often simple solutions to the problems once we know exactly what is going on.

When reporting delivery problems on Email infrastructure, make sure you include at least the following information in your report:

  1. originating email address (e.g. Alice <alice@torproject.org>)
  2. destination email address (e.g. Bob <bob@torproject.org>)
  3. date and time the email was sent, with timezone, to the second (e.g. 2019-06-03 13:52:30 +0400)
  4. how the email was sent (e.g. from my laptop, over SMTP+TLS to my email provider, riseup.net)
  5. what error did you get (e.g. a bounce, message not delivered)

Ideally, if you can, provide us with the Message-ID header, if you know what that is and can find it. Otherwise, don't worry about it and provide us with the above details.

If you do get a bounced message, do include the entire bounce, with headers. The simplest way to do so is forward it as an attachment or "view source" and copy-paste it somewhere safe (like https://share.riseup.net/).

Ideally, also include a copy of the original message in your report, also with full headers.

If you can't send a copy of the original message for privacy reasons, at least include the headers of the email.

Send us the message using the regular methods, as appropriate, see the support guide for details, but you should generally file an issue using the email problem template. Make sure you mark it as confidential.