Reports API - Contact Activity

Use the contact activity report to retrieve one contact's email history: which messages they were sent and what they did with each one (delivered, bounced, opened, clicked which links, unsubscribed), with a summary across all of them.

Authentication is via HTTP Basic Auth using your API ID and API Key.

Returns one JSON object with three parts: contact (who), summary (counts across every message), and messages (one entry per message, newest first, paged with limit and skip). Replace {ID} with the Envoke contact ID, the id of the Contact API.

A contact that does not exist, belongs to another account, or has been deleted returns [] with HTTP 200. A contact who has never been sent a message returns the object with every count 0, every time null, and messages [].

This report covers email messages only: form submissions and other contact events are not included.

Accounts restricted from contact-level email activity. On an account restricted from seeing contacts associated with email activity (the setting that hides a contact's Email sending history in Envoke), this endpoint and Find a Contact's Activity return HTTP 403; see Errors. The message reports are not affected.

limit and skip apply only to the messages array; contact and summary are always complete. Any other parameter, including sent_from and sent_to, returns HTTP 400 (Parameter 'sent_from' is not valid).

Returns the same object as Get a Contact's Activity for the contact found by email or by remote_id. Give exactly one of the two, plus any of activity_from, activity_to, limit, and skip. URL-encode the value (@ is %40).

The value is compared as a whole, exactly as the Contact API's filter[email] and filter[remote_id] compare it, so a value the Contact API finds is found here. Letter case does not matter: MAYA.CHEN@EXAMPLE.ORG finds the contact maya.chen@example.org, and a remote ID is matched the same way. An empty value is an error rather than a match for every contact without an email address or remote ID. When no contact matches, the response is [] with HTTP 200. When more than one contact matches, the request fails with HTTP 400 rather than choosing one; use the contact's id instead. More than one match is possible for remote_id, and for email on accounts that allow several contacts to share an address.

Counts of messages, across every message in the report (not only the current page of messages), inside the activity window when one is given:

Envoke records a contact's first open of a message in each email client and their first click on each link, never a repeat (see Times and time zone). So last_open_time is the latest of those first opens: a contact who reopens an old message in the same email client does not move it, but opening a new message, or the same message in another client, does. last_click_time works the same way for links.

One entry per message the contact was sent, ordered by sent_time, newest first, then by message id, highest first. A message is included when the contact has a send record for it and, when an activity window is given, at least one activity record for it inside the window. Messages the contact was selected for but skipped (no consent, invalid address) are not included. A message is listed whatever its status today, as on the contact page: a transactional message, or a message sent and later returned to draft, appears here even though the message reports do not answer for it.

In links, id is the tracked link's ID (the same as in the single-message report's links) and url is the link as written in the message with Envoke's tracking parameters removed, or "" for Envoke's own links (view online, preferences, poll answers). Merge tags in a link are not replaced, so url can be or contain a merge tag ({@customfield-url_test}, https://example.org/show?seat={@seat|url}) rather than a valid URL. first_click_time is the contact's first click on that link. For a message with an anonymous poll, poll-answer clicks are left out entirely, as in the Sent message report's drill-downs: they are not listed in links, not counted in clicks, clicked, or the summary (clicks and last_click_time), and do not by themselves place the message inside an activity window.

Activity window. With activity_from or activity_to, every flag and count reflects only the records inside the window, except sent_time, which is always the contact's send. A contact sent the message before the window who opened it inside the window shows opened true and delivered false, because the send is outside the window. delivered follows the message-level delivered: with a window it needs a send inside the window and no bounce for the message at any time.

Relation to the contact page. Each entry matches the row for the same message in the contact's Email sending history in Envoke (https://e1.envoke.com/contacts/{id}/delivery-history.json, .campaigns[] | {campaign_id, flags}): bounced, opened, and clicked equal its bounce, open, and click flags, except that on a message with an anonymous poll a contact whose only clicks were poll answers has clicked false where the page shows a click. A message the page lists from opens or clicks alone, with no send record for the contact, is not in this report. The app and this report both show times in your account's time zone.

Invalid requests return HTTP 400 with the validation envelope (see Error Responses). Besides the shared date, limit, skip, and unknown-parameter errors:

The 403 body:

Response (only 2004 had activity for this contact in May):

Response:

summary covers both messages; limit=1 returns only the newest in messages.

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

For code examples and interactive testing, visit api.envoke.com.