Email Routing

Overview uses GMail for organizational email and AWS SES for outbound transactional email to users.

In order to serve the public it is important that email is delivered reliably to the public when they sign up or make account changes. It is also important that team members receive email in order to support the public and agency partners.

This page provides an overview of how email is delivered to and sent from addresses. It includes command line examples showing how to check current DNS records and other SMTP related settings. Unless otherwise specified, all DNS records are served by AWS Route53 and all configuration is managed as code with Terraform.

Inbound Delivery to

GMail In

Inbound email to is directed by DNS MX records which list the SMTP servers that can receive email for addresses:

$ nslookup -type=mx

Non-authoritative answer:	mail exchanger = 30	mail exchanger = 30	mail exchanger = 30	mail exchanger = 30	mail exchanger = 10	mail exchanger = 20	mail exchanger = 20

Note - The top Server and Address lines show this lookup used the machine’s local resolver. Your tests may show a different address. In addition, note the Non-authoratative answer: and Authoratative answers can be found from: lines are due to using a forwarder instead of querying the authoritative DNS servers for directly. See Querying Authoritative DNS Servers if you wish to query’s authoritative DNS servers directly in cases of suspected DNS cache issues.

SMTP MTA Strict Transport Security (MTA-STS)

MTA-STS is roughly the equivalent of HTTP Strict Transport Security (HSTS) for email. It allows a domain to specify that all inbound email to the domain must use TLS and explicitly lists which names are allowed on the certificates used by receiving mail servers.

Implementation of MTA-STS requires both DNS and serving a web page that contains the policy for the domain. This allows end to end trust to be formed between the sending email system and receiving system using the same trust framework used for HTTPS.

WARNING - If receiving email servers are added or removed for, changes must be reflected in the MTA-STS policy to prevent inbound email to addresses from bouncing.

Due to the complexity in properly serving MTA-STS, developed a Terraform based method that:

  • Defines the list of MXes in code
  • Builds the policy file and pushes it to S3
  • Serve the policy file through an AWS CloudFront distribution
  • Publishes a TXT record using a fingerprint of the file in the id field
  • Publishes a `` TXT record defining what email addresses should receive MTA-STS delivery reports

To manually check the MTA-STS configuration:

  • Fetch the current policy from
  • Check the MTA-STS TXT record:
$ nslookup -type=txt

Non-authoritative answer:	text = "v=STSv1; id=59784add0f027f4ce93efbe6bc286e1a"
  • Check the reporting record:
$ nslookup -type=txt

Non-authoritative answer:	text = "v=TLSRPTv1;,"

See Runbook: Email and SMTP - MTA-STS for implementation details.

Outbound Sending from

GMail Out

Most team members send email using their address. Some Google Groups and other special addresses under do send out email. All outbound email from addresses


AWS Simple Email Service (SES) is used to deliver messages to users.

Sender Policy Framework (SPF)

Sender Policy Framework uses a TXT record to specify which mail servers (MXes) are allowed to send email out on behalf of a domain.

  • To check the SPF record:
$ nslookup -type=txt | grep spf descriptive text "v=spf1 ~all"
  • include elements reference other SPF records that include their own list of MXes. Notably:
    • - Amazon Simple Email Service (SES) servers, as used for transactional email
    • - Google GMail servers, as used for organizational email
  • ~all - Explicit deny of any other MX from sending email on behalf of

DomainKeys Identified Email (DKIM)

DomainKeys Identified Email (DKIM) allows a sending domain to declare cryptographic keys that will be used to sign all outbound email from the domain. Since uses GMail and SES, both of which have DKIM keys in place and published, we simply need to reference those keys in DNS. (As opposed to managing our own keys.) References are defined in TXT records as follows:

  • - SES-ID is a value obtained dynamically through AWS API calls using our ses_dkim_r53 Terraform module
  • - Explicitly defined and testable with nslookup -type=txt

Contact GSA email support if you have questions regarding DKIM keys for GMail.

Once the keys are defined they are referenced in outbound email as part of a DKIM signature value. Here is an example:

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=google;
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161030;

Domain-based Message Authentication, Reporting, and Conformance (DMARC)

DMARC allows a domain to define a set of policies applicable to email sent from the domain.

Flow Diagram (from RFC7498)

    | Author Domain |< . . . . . . . . . . . . . . . . . . . . . . .
    +---------------+                        .           .         .
        |                                    .           .         .
        V                                    V           V         .
    +-----------+     +--------+       +----------+ +----------+   .
    |   MSA     |<***>|  DKIM  |       |   DKIM   | |    SPF   |   .
    |  Service  |     | Signer |       | Verifier | | Verifier |   .
    +-----------+     +--------+       +----------+ +----------+   .
        |                                    ^            ^        .
        |                                    **************        .
        V                                                 *        .
     +------+        (~~~~~~~~~~~~)      +------+         *        .
     | sMTA |------->( other MTAs )----->| rMTA |         *        .
     +------+        (~~~~~~~~~~~~)      +------+         *        .
                                            |             * ........
                                            |             * .
                                            V             * .
                                     +-----------+        V V
                       +---------+   |    MDA    |     +----------+
                       |  User   |<--| Filtering |<***>|  DMARC   |
                       | Mailbox |   |  Engine   |     | Verifier |
                       +---------+   +-----------+     +----------+

Note the verification of DKIM and SPF. To check the DMARC policy for

$ nslookup -type=txt descriptive text "v=DMARC1; p=reject; pct=100; fo=1; ri=3600;,;"

The above specifies:

  • p=reject - Reject email if received email does not match policy
  • pct=100 - 100% of email is subject to filtering
  • fo=1 - Generate DMARC failure reports if SPF or DKIM checks did not pass
  • ri=3600 - Reporting Interval of 3600 (one hour) between reports
  •, - Send email delivery reports to the listed group and the standard DHS report destination
  • - Send forensic reports to the listed group

Querying Authoritative DNS Servers

If you are making DNS changes and want to validate the changes quickly without waiting for your DNS cache to expire and existing record, or if you suspect a DNS caching issue, you can query the authoritative DNS servers for using the following instructions.

  • Lookup the NS records using an official .gov nameserver:
$ nslookup -type=ns
Address:	2001:500:4431::2:30#53

Non-authoritative answer:
*** Can't find No answer

Authoritative answers can be found from:	nameserver =	nameserver =	nameserver =	nameserver =
  • Perform further lookups for records using an authoritative server by including the nameserver at the end of the query. For example, to get the list of MX records for using an the listed above:
$ nslookup -type=mx
Address:	2600:9000:5302:900::1#53	mail exchanger = 10	mail exchanger = 20	mail exchanger = 20	mail exchanger = 30	mail exchanger = 30	mail exchanger = 30	mail exchanger = 30

Note - Implementation of DNSSEC is pending for domains.

Further Reading