How to integrate PhishShield
PhishShield provides two ways to send email: through our SMTP relay or through our REST API. Once you've determined how you want to send your email, we recommend you take a quick look at domain integration to make sure your branding is in the emails you send.
Sending email through our SMTP relay is the easiest way for an application to use PhishShield because it only requires updating your SMTP configuration.
- Change your SMTP username to the username of the Pool or IP Address you want to send from. For most use cases, you should use the Global Pool.
- Set the SMTP host of your relay to smtp.phishshield.com.
- Use port 465 for TLS connections and port 587 or 2525 for plain connections. 587 and 2525 can be made secure by upgrading the connection with the STARTTLS command, which is supported by most mail clients.
The REST API has some advantages over SMTP:
- If your ISP or hosting provider blocks traffic on mail ports.
- If you do not control your hosting environment and cannot install/configure an SMTP library.
You can look at the full API documentation here.
To give PhishShield permission to send mail on your behalf and properly collect analytics, you point DNS entries from your DNS provider (like GoDaddy, Rackspace, or Route53) to PhishShield.
Verifying your domain and organization name
You will need to create a DNS TXT entry on any domain you want to send from with the special value specified on this page.
Once you've verified your domains, you can verify your organization name. Your organization name is branding that is included on the verification page when a user sets up their PhishShield account and verifies your email. If you do not specify an organization name, we'll just use the "your organization" verbiage.
Setting MAIL FROM
In order for PhishShield to collect delivery status information, we set the MAIL FROM in your emails to yourhost.smtp.phishshield.com. As a result, email clients will generally append via yourhost.smtp.phishshield.com next to where the "From" field is displayed.
We recommend you create a DNS entry for a mailer domain that will be a CNAME to yourhost.smtp.phishshield.com, and setting the MAIL FROM address from the Your IPs page to this mailer domain. Note: you must have a dedicated IP plan in order to update your IP address settings.
For example, create a domain like:
NAME mailer.yourdomain.com IN CNAME "yourhost.smtp.phishshield.com"
Once you update the MAIL FROM address on the Your IPs page, emails will now have via mailer.yourdomain.com.
To completely get rid of the via mailer.yourdomain.com, you need to set up DKIM and SPF. The following sections will teach you how to set up these email authentication protocols.
DKIM stands for DomainKeys Identified Mail and is an email authentication method to help prevent spoofing. DKIM lets an email server associate its name with a sending domain by affixing an email signature of the email contents to the email headers. An email client can calculate the signature using the sending domain's DNS records (which is public to the internet) and compare this against the signature sent in the "DKIM-Signature" header in the email that was sent. If the two signatures are equal, then the email client can be sure that the email was sent by an authorized domain.
DKIM alignment is when your DKIM signing domain matches the Header From domain. The two types of DKIM alignment are relaxed alignment and strict alignment. If you do not specify strict alignment, relaxed alignment is assumed.
This alignment type requires the DKIM domain to match the root Header From domain. Relaxed alignment is the default. Relaxed alignment allows a subdomain to be used and still meet the domain alignment requirement.
If your DKIM domain is mail.example.com and your Header From is example.com, your email would pass DKIM alignment. The root domains example.com match.
If your DKIM domain is example.mail.com and your Header From is example.com, your email would not pass DKIM alignment. The root domains mail.com and example.com do not match.
This alignment type requires the DKIM domain to match the Header From domain exactly.
If your DKIM domain is mail.example.com and your Header From domain is example.com, your email would not pass DKIM alignment.
If your DKIM domain is mail.example.com and your Header From domain is mail.example.com, your email would pass DKIM alignment.
Setting your DKIM domain
Specifying a default DKIM domain for your IP address in the Your Pools page will set that as the DKIM domain for all emails sent from that Pool.
If you've enabled DKIM on a Pool but do not specify a default DKIM domain, PhishShield will automatically use the Header From root domain. For example, if you send mail using Header From some.mailer.example.com, we will set the DKIM domain to example.com.
Make sure to set a DNS CNAME record for every domain you plan on sending from. You can find this value from the "DKIM Record" value on any of your pools. To ensure deliverability from all of your Pools and IP Addresses, this value will be the same for anything you want to send from. This means you only have to set up DKIM once and you will be able to send email through new Pools or IP Addresses you provision over time.
The DKIM selector will always be "ps".
This will set up DKIM on the example.com domain:
NAME ps._domainkey.example.com IN CNAME "domainkey.yourhost.smtp.phishshield.com"
The CNAME value you set will always be of the format domainkey.yourhost.smtp.phishshield.com. Once you've set up your records, you can test them with the dig application:
1 2 3 4 5 6 7 8 9 10 11 12 13
dig ps._domainkey.yourdomain.com TXT ; <<>> DiG 9.8.3-P1 <<>> ps._domainkey.yourdomain.com TXT ;; global options: +cmd ;; Got answer: ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 5734 ;; flags: qr rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 0 ;; QUESTION SECTION: ;ps._domainkey.yourdomain.com. IN TXT ;; ANSWER SECTION: ps._domainkey.yourdomain.com. 300 IN CNAME domainkey.yourhost.smtp.phishshield.com. domainkey.yourhost.smtp.phishshield.com. 110 IN TXT "k=rsa; t=s; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDtbgOiOg5lp2mWKxd6fyzM+BJ0Gyj/vQY1vZFIClrukUF2039rfVMfH66VGt0RtUrSOxqc1hi9nqAKuXiw/+MtN48DwYuXKiOSSQ5wyoW3K2wpf1s0kS7DEVBzOJLv2Aa/2Z//vPiAjb01Q0cQKliGYmn4tSh318zSeYyUWFu7ywIDAQAB"
Enabling DKIM on an IP but not having the relevant DKIM TXT records will negatively affect deliverability, so make sure you add those records before sending mail from new domains.
If you do not enable DKIM on an IP address, then you do not need to have any of these records in place. However, having valid DKIM records DOES improve deliverablity and we strongly recommend that your organization enables it.
SPF stands for Sender Policy Framework and is an email validation protocol designed to detect and block email spoofing by providing a way for email clients to verify that incoming mail from a domain comes from an IP Address authorized by that domain's administrators.
SPF is one of the most important mechanisms for email deliverability and is required to authorize PhishShield to send email on your organization's behalf.
SPF alignment is when your MAIL FROM (envelope-from) domain matches the Header From domain. The two types of SPF alignment are relaxed alignment and strict alignment. If you do not specify strict alignment, relaxed alignment is assumed.
With relaxed alignment, only the root domain of the MAIL FROM address must match the root domain of the Header From address. Relaxed alignment allows a subdomain to be used and still meet the domain alignment requirement.
If your MAIL FROM domain is mail.example.com and your Header From is example.com, your email would pass SPF alignment. The root domains example.com match.
If your MAIL FROM domain is example.mail.com and your Header From is example.com, your email would not pass SPF alignment. The root domains mail.com and example.com do not match.
With strict alignment, the domain of the MAIL FROM address is an exact match for the domain of the Header From address.
If your MAIL FROM domain is mail.example.com and your Header From is mail.example.com, your email would pass SPF alignment.
If your MAIL FROM domain is mail.example.com and your Header From is example.com, your email would not pass SPF alignment.
Setting your SPF domain
In order to determine if the email server is authorized to send mail from that address, an email client will look up the DNS record for yourdomain.com. This record is a simple TXT record and may look something like this:
NAME yourdomain.com IN TXT "v=spf1 include:yourhost.smtp.phishshield.com ~all"
You can find the correct host value to set by looking at the "SPF Record" field on any of your Pools or IP Addresses. To ensure deliverability from all of your Pools and IP Addresses, this value will be the same for anything you want to send from. This means you only have to set up SPF once and you will be able to send email through new Pools or IP Addresses you provision over time.
The above SPF record authorizes PhishShield to send email on behalf of yourdomain.com. As long as the server sending email matches this domain, the email will pass the SPF check. If not, the email client will be unable to verify the sender identity and will most likely flag your email as spam.
DMARC stands for Domain-based Message Authentication, Reporting and Conformance and is an email-validation system designed to detect and prevent email spoofing by solving operational and reporting issues related to the SPF and DKIM email authentication protocols.
To pass DMARC, your email must pass either or both of:
- SPF authentication and SPF alignment
- DKIM authentication and DKIM alignment
DMARC instructs mailbox providers on how to handle unauthenticated email through a DMARC policy that you create in a DNS TXT record. This removes any guesswork on how mailbox providers should handle messages that fail DMARC authentication.
Mailbox providers send regular DMARC aggregate and forensic reports back to senders, giving you visibility into what messages are authenticating, what messages are not and why.
For example, the following DMARC record will notify firstname.lastname@example.org on a failed check:
NAME _dmarc.example.com IN TXT "v=DMARC1; p=none; rua=mailto:email@example.com"