API: Searching for Emails
This document provides a guide for software developers to use the Archiver REST API.
An email search is performed by posting search criteria to the email search resource. Be sure to pass the authorization token using an Authorization HTTP header.
Service URL:
| post | /api/v1/email/search |
|---|
The service URL will depend on whether your Archiver account is hosted within the US or EU. Please ask your Sageflo Account Manager if you are not sure which to use.
Request Method:
Post
HTTP Headers:
Authorization: <AUTHORIZATION TOKEN>Content-Type: application/json
Request JSON:
{
"email": "<The email address to search for>",
"start_date": "<M/D/YYYY formatted date. Beginning of date range to search, inclusive>",
"end_date": "<M/D/YYYY formatted date. End of date range to search, inclusive>",
"sub_account": "<If your account is configured with multiple sub accounts, a sub account name can be used to filter your results>",
"subject_keywords": "<subject line keywords, separated by spaces>",
"platform_campaign_id": "<ESP Campaign ID>",
"purpose": "<TRANSACTIONAL or PROMOTIONAL>",
"marketing_program": "<Marketing program name>",
"marketing_strategy": "<Marketing strategy name>",
"from_email": "<From email address>",
"from_name_keywords": "from name keywords, separated by spaces",
"custom_field_filters": [
{
"name": "<filter_name>",
"value": "<filter_value>"
}
]
}
Note: For the request JSON, the only required fields are:
"email"
"start_date"
"end_date"
The exception to this rule is if your account is configured with a unique custom field filter, in which case the custom field could be used instead of the "email" and "start_date", "end_date".
Sample Request JSON:
{
"email": "johnsmith@google.com",
"start_date": "11/26/2019",
"end_date": "1/1/2020"
}
HTTP Status Code:
The API will return 200 for a successful search, even if no results were found.
It will return 4** for errors.
Response JSON:
Search results come back as an object, containing an array of individual email objects in the "results" attribute.
{
"results": [
{
"email": "<Recipient Email address>",
"campaign_name": "<Email Campaign Name>",
"campaign_purpose": "<PROMOTIONAL or TRANSACTIONAL>",
"from_email": "<Sender email address>",
"from_name": "<Sender name (friendly from)>",
"is_campaign_avail": "<True or False indicates if campaign info was available at time of search>",
"email_url": "<URL of email contents>",
"locator": "<The locator of an email, which can be used to resend the email>",
"marketing_program": "<Marketing Program>",
"marketing_strategy": "<Marketing Strategy>",
"platform_campaign_id": "<Platform campaign id>",
"sent_dt": "<Timestamp in UTC of email send>",
"sub_account_name": "<Sub Account Name>",
"subject": "<Subject line>"
}
]
}
Sample Response JSON:
{
"results": [
{
"campaign_name": "Campaign Name",
"campaign_purpose": "PROMOTIONAL",
"email": "johnsmith@google.com",
"from_email": "sender@sender.com",
"from_name": "Subscriber Deals",
"is_campaign_avail": true,
"email_url": "https://archiver.sageflo.com/api/v1/email/\nbGlmdHNjaWVuY2UudGVzdC5idWNrZXR8fDIwMTYwMjE1LWRlbW8tZW1haWxzfHwyNTM4NzR8f",
"locator": "\nbGlmdHNjaWVuY2UudGVzdC5idWNrZXR8fDIwMTYwMjE1LWRlbW8tZW1haWxzfHwyNTM4NzR8f",
"marketing_program": "Marketing program name",
"marketing_strategy": "Marketing strategy name",
"platform_campaign_id": 1462,
"sent_dt": "2019-11-26T08:00:00.000Z",
"sub_account_id": "Sub Account Name",
"subject": "You've been rewarded! 20% OFF + Free Shipping on your ENTIRE ORDER!"
}
]
}