There are AMP components for everything from carousels, to responsive form elements, to retrieving fresh content from remote endpoints. The AMPHTML Email format provides a subset of AMPHTML components for use in email messages, that allows recipients of AMPHTML emails to interact dynamically with content directly in the message.
This guide is a high-level overview of implementing support for the AMPHTML email format, aimed at Email Providers. For further technical details, please see the spec.
- AMPHTML Email Specification
- Validate AMPHTML Emails
- Add an AMP Viewer
- Spam Check and Sanitize Spam
- Include a Proxy Server
- Update CORS Headers
- Set Standard Security Measures
- Understand Allowed CSS properties and selectors
- Signify a Change and Set a Fallback
- Current AMPHTML Email Support
AMPHTML Email Specification
The AMPHTML Email Specification has been added to the AMPHTML project. It covers AMPHTML Email in detail and includes answers to specific questions and provides guidelines for general AMPHTML Email developers.
Validate AMPHTML Emails
It is important to user security and experience that emails sent with AMP HTML are validated as proper AMP documents. The AMP validator ensures that AMPHTML Emails are respecting the AMPHTML Email (
⚡4email) spec and make proper use of AMP components. Email Providers are highly encouraged to run the validator prior to rendering the message as a sanity check. In case the AMPHTML Email is not valid, the HTML version can be used as rendering fallback.
Add an AMP Viewer
An AMP viewer is required to display AMPHTML emails and keep the user experience secure. An AMP Viewer sandboxes content, allows communication between the AMP runtime and the embedding client, isolates content on a different domain, and allows the proxying of XHR.
The AMP project has published two versions of the AMP Viewer, that use a WebView or iframe to show an AMP document with additional functionality you may need. The AMP Viewer can be used directly or as an example for your implementation.
Further documentation on the AMP Viewer can be found here.
While AMPHTML Emails provides certain level of security, a few more measures must be taken to safely provide users with the features and interactivity of AMP components.
Spam Check and Sanitize Spam
While the AMP Validator will only allow whitelisted components through, a spam checker should analyze and sanitize an AMPHTML Email much like it would analyze a regular HTML email. The system should also ensure the email passes at minimum DKIM, DMARC, and SPF checks. Furthermore, a sender whitelist is also a strong way to mitigate risks.
Include a Proxy Server
A proxy server is fundamental and should be responsible for handling XHR requests that originate from the AMPHTML Emails (e.g. from amp-list, amp-form, etc) and perform spam checks and sanitization on the content fetched by these requests.
Some dynamic elements in AMPHTML Emails may rely on remote content. Additional steps should be taken to prevent user data, such as IP address, cookies, and type of device, from being leaked to third party endpoints and giving rewrite access to parts of the AMPHTML Email.
Update CORS Headers
Since the requests go through a proxy server, the AMPHTML Email CORS requirements are slightly different than the existing AMP CORS requirements.
The following describes what headers to expect in a request from each source and the headers that should be included in the response by the server.
All requests coming from your proxy servers should contain the following:
(Header) Origin: https://MAIL.YOURDOMAIN.com (Query parameter) __amp_source_origin=<sender email address>
For example, an XHR request that originated from an email sent by email@example.com would have the following header and query parameter:
(Header) Origin: https://MAIL.YOURDOMAIN.com (Query parameter) firstname.lastname@example.org
The endpoints used in the email will verify these values and reject any requests that do not contain these two values.
All responses should contain the following 3 headers:
Access-Control-Allow-Origin: https://MAIL.YOURDOMAIN.com AMP-Access-Control-Allow-Source-Origin: <your sender email address> Access-Control-Allow-Source-Origin: AMP-Access-Control-Allow-Source-Origin
For example, if the email was sent by email@example.com, then the headers should look like the following:
Access-Control-Allow-Origin: https://MAIL.YOURDOMAIN.com AMP-Access-Control-Allow-Source-Origin: firstname.lastname@example.org Access-Control-Allow-Source-Origin: AMP-Access-Control-Allow-Source-Origin
If the response does not contain these headers, your proxy server should reject the response and AMP should not render the response.
Set Standard Security Measures
It’s worth saying that security is an ongoing concern, and you should have a good security and risk mitigation plan. It is crucial to have measures in place to apply if a new vulnerability is found, and you may need to have a quick way to disable AMPHTML Emails, block senders, block XHR requests to servers, etc.
On top of your current spam/phishing mitigation strategies, it is imperative to include new ones for the new XHRs requests. Render content derived from all XHR requests after performing spam, phishing and sanitization checks.
Understand Allowed CSS properties and selectors
AMPHTML Email does not restrict CSS itself. However, CSS allowed within email messages vary depending on the email provider. For reference, the list of CSS properties and values allowed in Gmail can be found at Gmail Supported CSS Properties & Media Queries, other Email Providers are encouraged to also publish a similar list to help developers/creators.
Signify a Change and Set a Fallback
Make clear to the user that the email is an AMPHTML email and offer the regular HTML version as an alternative. If an invalid AMPHTML email is sent, render the HTML version as a standard fallback. For older emails, you may need to store and use older versions of the AMP runtime when new ones are released for breaking changes.
Current AMPHTML Email Support
Gmail will support AMPHTML emails on iOS, Android, and Web. We're working with other email providers and clients to have their Web and mobile apps support it as well. Please reach out by filing an issue on GitHub if you’re interested in including AMPHTML Emails in your service.