Email DKIM

This guide is intended to assist Systems Administrators implement DomainKeys Identified Mail (DKIM) email authentication in Schoolbox. DKIM support was added in version 22.1.

DKIM enables the email recipient to verify that an email that claims to come from a particular domain was indeed authorisied by the owner of that domain.

How does it work?

Schoolbox sends two general forms of email:

1. From a system email address configured in the admin area (Email From Address), eg schoolbox@domain1.com
2. On behalf of end users of the system. eg john.smith@domain2.com

In these examples the domains are domain1.com and domain2.com respectively.

The following steps illustrate how DKIM enables email sent from these domains to be verified by the recipient and ensure delivery.

1. For each domain the system sends mail from (domain1.com and domain2.com in the example above) and for which DNS management is available: 
   1. a public/private keypair is generated via the Schoolbox admin interfaces at /adminv2/email-dkim
   2. the public key is used to create a DNS TXT record in the domain's DNS zone
2. When Schoolbox generates an email from a domain for which a public/private keypair has been generated:
   1. Schoolbox signs the email with the private key and routes the message to the recipient's mail server
   2. The recipient mail server fetches the public key from the domain's DNS and verifies the message signature
   3. The recipient mail server uses the signature verification result and other reputation factors (sending IP, message content, SPF, DMARC policy etc) to determine whether to deliver the message, mark the message as spam, or reject it.

The following steps illustrate how to configure Schoolbox to sign messages sent from a particular domain. In all steps below, replace example.com with the your domain.

1. Navigate to the Schoolbox DKIM configuration page at /adminv2/email-dkim
2. Click the + icon in the top right to add a domain. 
3. In the modal, enter your domain and click the Add button. The system will generate a private/public key pair for this domain.
4. In the list of domains, click the domain you just added. The system will display the required DNS TXT record name and value.
5. In the domain's DNS zone, create a new TXT record with the displayed name and value
6. Check the DNS TXT record exists with the expected value, eg via an online service: https://dnschecker.org/#TXT/schoolbox._domainkey.example.com 
7. In Schoolbox, modify your user to have an email address with the domain for which DKIM was just configured, eg test@example.com
8. Log out and log back in to ensure the email address change is applied
9. Send a test email from /mail/create  to a an email address whose mail server checks DKIM (eg Gmail)
10. Check the delivered email's headers for DKIM signature and signature verification results
    1. There should be a header named DKIM-Signature that was added when Schoolbox generated the email
    2. There should be a header named Authentication-Results or logically similar added by the recipient mail server that indicates DKIM signature verification