Archiving file attachments
If an email includes file attachments, e.g. images, documents, audio, etc., you must send the files to the /files endpoint before you reference them in the /email request.
For each attachment, make a PUT request to the /files endpoint, with your chosen fileKey included as a URL path parameter:
curl -X PUT "email.api.globalrelay.com/v2/files/default/documents/<filename>.pdf" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-H "Content-Type: <VALID_CONTENT_TYPE>" \
-T "<PATH_TO_FILE>"If you use the same fileKey for multiple requests, the API returns a 200 success response, and the original file is replaced with the new version specified in the latest request.
You must include “/default” in the URL path before the file name. The path from “default” onward, e.g. “default/documents/Q3-report-2023.pdf”, will be the fileKey value you reference in the /files endpoint.
Handling different file types
The file should be sent as binary data in the body of the PUT request, and you should include a Content-Type header with a standard MIME type describing the format of the contents.
If the file type is unknown, you can use the generic “application/octet-stream” type; however, the file type will not be obvious to a user of the Archive and they may not be able to open the file.
A Content-Length header is not required; however, if you send an incorrect value, only the amount of data specified in the header will be captured, which could result in incomplete data being archived. As per RFC 9110, the Content-Length should be the uncompressed, decrypted file size as a decimal, non-negative integer number of octets.
The /files endpoint supports files up to 1.0GB in size. If you send a file larger than this, the API returns a 400 error.
Referencing attached files
Once you receive a 200 success response from the /files endpoint for all files referenced in the email, make a request to the /email endpoint referencing the files in the file object of the request.
It’s essential that the fileKey in this request matches the fileKey uploaded via the PUT /files endpoint.
If you provide a fileKey that is not found in your Archive, the POST /email request will return a 400 error response and the associated email data will not be archived.
Referencing external file locations
You can also include links to externally located files, including cloud attachments, by referencing the URL in the fileHref field along with the mandatory fileKey and filename fields. Externally located files are not captured in Global Relay Archive.
When users view email data in your Archive, the filename will be the text displayed on the link to the URL you supply in the fileHref. The fileKey is not displayed, but must be populated with some value in the API request.