v1

latestOpenAPI 3.1.02026-07-24700259.3 KB

ACTIVITY

Search activity

Returns events (such as opens, unsubscribes) which match the filters passed. A count of events matching the filter is also included, as this may surpass the maximum of 1,000 items included within the response. This endpoint is rate-limited to 60 requests per minute.

post/activity/search

Request body

start_datestring

end_datestring

ISO-8601 formatted datetime which defaults to now. Timezone is UTC.Defaults to current date at midnight. Valid formats are: <code>2006-01-02</code>, <code>2006-01-02 15:04:05</code>, <code>2006-01-02T15:04:05</code>, <code>2006-01-02T15:04:05.0000000</code>, <code>02 Jan 06 15:04 MST</code>, <code>02 Jan 06 15:04 -0700</code>, <code>2006-01-02T15:04:05Z07:00</code>, <code>2006-01-02T15:04:05.999999999Z07:00</code>, <code>Mon, 02 Jan 2006 15:04:05 MST</code>

searchstring

If passed, will return all events for emails containing this string in any search fields. To return events with one or more text values, separate the text with '|' (e.g. 'text1 | text2')

search_email_idstring

If passed, will return all events for an email matching this specific id

search_subjectstring

If passed, will return all events for emails containing this string in the email subject

search_senderstring

If passed, will return all events for emails containing this string in the email sender

search_recipientstring

If passed, will return all events for emails containing this string in the email recipient

search_usernamesstring[]

If passed, will return all events for emails sent by this/these username/s

subaccountsstring[]

If passed, will return all events for emails sent by this/these subaccount_id/s (as returned from the <code>/subaccount/search</code> endpoint or as shown in the App)

limitinteger

The maximum number of events to return (Max: 1000)

continue_tokenstring

If passed, will continue the search beyond the current page, using the same search parameters

only_latestboolean

If true, will only return the most recent event for each email returned. Default: false

only_latest_by_sentboolean

If true, will only return the most recent event for each email returned ordered by sent date (overrides only_latest field). Default: false

event_typesstring[]

If passed, will limit the returned events to the provided event types. Values: 'processed', 'soft-bounced', 'hard-bounced', 'rejected', 'spam', 'delivered', 'unsubscribed', 'resubscribed', 'opened', 'clicked'

include_headersboolean

Return the full email headers with the response

custom_headersstring[]

A list of header keys to parse out of the raw headers

region'us' | 'eu' | 'au'

Optional. By default, activity search queries the region where the master account is located. If the account has subaccounts in other regions, pass this field to force the search to query activity data in that region.

Example request

{
  "custom_headers": [
    "X-MyCustomID"
  ],
  "region": "us"
}

Response

Matching events

request_idstring required

Example response

{
  "data": {
    "continue_token": "...",
    "events": [
      {
        "from": "no-reply@example.com",
        "recipient": "someone@example.com",
        "subaccount_name": "Master account",
        "email_id": "1u0SwL-B9zBpi9ffUq-JAB2",
        "date": "2021-02-09T12:18:53Z",
        "event": "opened",
        "subject": "Booking Confirmation",
        "username": "smtpuser",
        "reply_to": "reply@example.com",
        "sender": "no-reply@example.com",
        "sender_full": "NoReply <no-reply@example.com>",
        "to": "otherperson@example.com",
        "cc": "cc@example.com",
        "bcc": "bcc@example.com",
        "smtp_response": "250 Message received",
        "reason": "This was a spam email",
        "host": "127.0.0.1",
        "originating_host": "127.0.0.1",
        "error": "i/o timeout"
      }
    ],
    "total_events": 23405
  },
  "request_id": "4b661d88-6b2d-11eb-8bb3-f23c92bb31d2"
}