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 is listed may be used as a sender. Any other sender address used is rewritten.

  1. Ensure SPF and DKIM records are set

    See DNS Records for Outgoing Mails

  2. Set allowed domains:

     abc:   # <- customer
       mail_domains:             # <= List domains here            # <=
  3. Apply change:

    ansible-playbook playbook.yml -t mail -l ${INSTALLATION}


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

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
       disable_dkim_check: true    # <= disable DKIM verification
       disable_spf_check: true     # <= disable SPF verification

Expect mails to end up in spam or be refused. Particularly, with a missing or incorrect SPF.

Configure Default Sender Addresses

  1. Set mail addresses in config.yml:

    abc:   # <- customer
      mail_sender_default:     # <= Address used when sender domain is not listed
                                           #    in `mail_domains` and no default is set on
                                           #    business unit.
      mail_sender_noreply:  # <= Address used in in special context where
      installations:                       #    replying doesn't make sense. For instance,
        abc:                               #    on the password reset mail.

    The domains of the sender addresses must be listed in mail_domains. See above.

  2. Apply change:

    ansible-playbook playbook.yml -t mail -l ${CUSTOMER}

Default Domain

The domain is used as fallback for outgoing mail when no domain is configured explicitly. That is, the following is used as default:


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:

      # only send out mails to domains/addresses listed
      # in mail_allowed_recipients
      mail_allowed_recipients_enabled: true
      # send out all mails
      mail_allowed_recipients_enabled: false


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.
  mail_allowed_recipients: !merge


Always use the !merge type (Merge Variables) to extend the default which includes and

Redirect discarded mails config.yml:


This will redirect any mail to a non-whitelisted recipient to

Configure Mail Relay

For customers using their own mail relays, the following options can be used for configuration:

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.