Understanding the key resources
There are 2 key resources in the Email payload you send in an API request:
Email Overview
This consists of metadata about the email:
- messageId: A unique identifier used to identify the email. This identifier can be reused by subsequent emails in a thread, i.e. replies and forwards of the email. If you do not provide a messageId, one will be generated.
- *time: The time, in epoch milliseconds, when the email was sent.
- subject: The subject of the email. If you do not provide a subject, one will be generated in this format: <platformtype>: <subtype>: <Number of Users>
- *senders: A list of senders, which can include the From and Sent on behalf of senders.
- *recipients: The users who received the email.
- *content: The content of the body of the email.
- files: Identifies any files that were attached to the email. For more information about attaching files to emails, see Archiving an email with attachments.
- emailProperties: Additional properties, i.e. headers, that were sent as part of the email. You can include up to 10 headers. For more information on adding custom x-headers to your emails, see Adding custom headers.
- eventType: These represent the type of email events that occurred, i.e.
Email_Sent, Email_Received, Email_Forwarded, Email_Replied, Email_Replied_All, Email_Bounced, Email_Draft, Email_Deleted, Email_Read, Email_Unread, Email_Archived, Email_Recalled, Email_Sent_On_Behalf, Auto_Reply, Email_Scheduled
* Identifies mandatory metadata that must be sent in each call.
Request Info
In the Request Info object, provide a unique ID (UUID), which you can use for tracking purposes. For more information about the Email payload, refer to the API reference.
Grouping emails by conversation threads across requests
You can reuse the same messageId in API requests, so emails as part of a thread, e.g. replies and forwards, display as single, sequential conversations in the Archive.
For example, this is the first payload you send for an email:
"requestInfo": {
"requestId": "2c8d4927-433c-4e9a-bf02-ead2f17d1ef2"
}
"emailOverview": {
//
"messageId": "1fbbfbe2-aaaa-bbbb-cccc-2df67b3fb23"
//
}If an email thread continued after the first API request was sent, you should send another request with a different requestId, but the same messageId for all subsequent emails in the thread:
"requestInfo": {
"requestId": "f8bd53a8-3b72-11ee-be56-0242ac120002"
}
"emailOverview": {
//
"messageId": "1fbbfbe2-aaaa-bbbb-cccc-2df67b3fb23"
//
}Tracking your requests
When sending a request to the POST /email endpoint, you must include a UUID in the requestId field, which identifies this specific API request. Because we log the requestId for data reconciliation purposes, you should send a unique value in each request.
The requestId is visible in the Archive when viewing the related email data.
"requestInfo": {
"requestId": "2c8d4927-433c-4e9a-bf02-ead2f17d1ef2"
}Refer to RFC 4122 for information on the UUID standard.
All your data in the Archive is immutable, so we deliberately don’t support updates. If you send us two different payloads with the same requestId we will still archive them independently.
For all successful API requests, you receive a randomly-generated reconciliationId in the response, which is mapped to the requestId in Global Relay’s system.
Identifying duplicate messages
Improve the transparency of your requests while effectively detecting and managing duplicate submissions without additional calls or logic.
If you post a duplicate message entry to the Email Archiving API, a 202 Accepted HTTP response code is returned. The response code indicates the entry is a duplicate of a previously archived entry, as shown in the following example.
HTTP/1.1 202 ACCEPTED
content-type: application/json
{
"status": "duplicate"
"reconciliationId" : “<reconciliationId>”
}In the response, the reconciliationId corresponds to the original message entry that was successfully processed, so you can trace the duplicate to its corresponding archived EML entry.
Including additional metadata for your conversations
You can use the emailProperties key/value pair object to capture any additional metadata about an email.
This is useful if you need to capture information which isn’t otherwise represented in the email payload. For example, you can capture geographical data or the time zone of the participants.
You can view and search for the data included in this object on messages in the Archive.
Understanding email size limits
For the /email endpoint, the maximum volume of data you can send in a single request is 10 MB – this does not include file attachments, which are sent to the /files endpoint.
If you exceed 10 MB, the API returns a 413 error.
When Global Relay receives your data, it is transformed into our Archive message format for optimal indexing. In the rare instance the combined size of the email text, metadata, and file attachments exceeds 2GB, the email is split into multiple Archive messages.
For more information on archiving attachments, see Archiving file attachments. To locate all the messages for an email thread in the Archive, conduct an Archive header search using the messageId you provided in the payload.