This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.
Ansible: Email Settings¶
Configure Email Sender Domains¶
This is a list of domains that may be used as sender in emails. For instance, if tocco.ch is listed someuser@tocco.ch may be used as a sender. Any other sender address used is rewritten.
Ensure SPF and DKIM records are set
Set allowed domains:
abc: # <- customer mail_domains: abc.ch: # <= List domains here abc.net: # <= installations: abc: abctest:
Apply change:
ansible-playbook playbook.yml -t mail -l ${INSTALLATION}
Hint
In case SPF/DKIM has not been configured yet or the customer is unable or unwilling to configure it, consider not setting a domain at all and using our default, fallback domain. See Default Domain tocco-mailing-service.ch
While strongly discouraged, it’s possible to set a mail_domain without adding a SPF or DKIM record by disabled the automated check:
abc: # <- customer
mail_domains:
abc.ch:
disable_dkim_check: true # <= disable DKIM verification
disable_spf_check: true # <= disable SPF verification
abc.net:
Expect mails to end up in spam or be refused. Particularly, with a missing or incorrect SPF.
Configure Default Sender Addresses¶
Set mail addresses in config.yml:
abc: # <- customer mail_sender_default: info@abc.ch # <= Address used when sender domain is not listed # in `mail_domains` and no default is set on # business unit. mail_sender_noreply: noreply@abc.ch # <= Address used in in special context where installations: # replying doesn't make sense. For instance, abc: # on the password reset mail. abctest:
The domains of the sender addresses must be listed in
mail_domains
. See above.Apply change:
ansible-playbook playbook.yml -t mail -l ${CUSTOMER}
Default Domain tocco-mailing-service.ch¶
The domain tocco-mailing-service.ch is used as fallback for outgoing mail when no domain is configured explicitly. That is, the following is used as default:
mail_domains:
- tocco-mailing-service.ch
mail_sender_default: noreply@tocco-mailing-service.ch
mail_sender_noreply: noreply@tocco-mailing-service.ch
This domain is under Tocco’s control and may be used when a customer does not wish to use their own domain or as an interim solution while the customer is setting up DKIM/SPF for their domain.
Restrict Allowed Mail Recipients¶
It’s possible to restrict outgoing mails to certain domains or addresses by rewriting the recipient address of mails not explicitly whitelisted.
Enable/disable whitelist in config.yml:
abc:
installations:
abc:
# only send out mails to domains/addresses listed
# in mail_allowed_recipients
mail_allowed_recipients_enabled: true
abctest:
# send out all mails
mail_allowed_recipients_enabled: false
Tip
By default, mail_allowed_recipients_enabled is set to true on test systems and false on production.
Extend whitelist in config.yml:
# This should generally be set on customer level.
abc:
mail_allowed_recipients: !merge
- example.com
- jane@example.net
Tip
Always use the !merge type (Merge Variables) to extend the default which includes tocco.ch and mail-tester.com.
Redirect discarded mails config.yml:
abc:
mail_blackhole_address: joe@example.net
This will redirect any mail to a non-whitelisted recipient to joe@example.net.
Configure Mail Relay¶
For customers using their own mail relays, the following options can be used for configuration:
mail_relay: mail.smtp2go.com
mail_relay_port: 25
mail_relay_user: user@domain.tld
mail_relay_password: '{{ secrets2.mail_relay_password.CUSTOMER_NAME }}'
Put password in secrets2.yml. Look at existing mail_relay_password entries in config.yml and secrets2.yml for guidance.