---
title: "Search activity"
method: POST
path: "/activity/search"
tags: ["ACTIVITY"]
---

# Search activity

`POST /activity/search`

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.<br /><i>This endpoint is rate-limited to 60 requests per minute.</i>

## Request body

- object
  - `start_date` string
  - `end_date` string — ISO-8601 formatted datetime which defaults to now. Timezone is UTC.Defaults to current date at midnight.<br><br>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>
  - `search` string — 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_id` string — If passed, will return all events for an email matching this specific id
  - `search_subject` string — If passed, will return all events for emails containing this string in the email subject
  - `search_sender` string — If passed, will return all events for emails containing this string in the email sender
  - `search_recipient` string — If passed, will return all events for emails containing this string in the email recipient
  - `search_usernames` string[] — If passed, will return all events for emails sent by this/these username/s
  - `subaccounts` string[] — 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)
  - `limit` integer — The maximum number of events to return (Max: 1000)
  - `continue_token` string — If passed, will continue the search beyond the current page, using the same search parameters
  - `only_latest` boolean — If true, will only return the most recent event for each email returned. Default: false
  - `only_latest_by_sent` boolean — If true, will only return the most recent event for each email returned ordered by sent date (overrides only_latest field). Default: false
  - `event_types` string[] — If passed, will limit the returned events to the provided event types.<br><br><strong>Values:</strong> 'processed', 'soft-bounced', 'hard-bounced', 'rejected', 'spam', 'delivered', 'unsubscribed', 'resubscribed', 'opened', 'clicked'
  - `include_headers` boolean — Return the full email headers with the response
  - `custom_headers` string[] — 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.

## Response `200`

Matching events

- object
  - `data` object, required
    - `continue_token` string, nullable, required
    - `events` object[], required
      - `from` string, required
      - `recipient` string, required
      - `subaccount_name` string, required
      - `email_id` string, required — The unique ID of the email which generated the event
      - `date` string, required — An RFC3339 encoded timestamp with UTC timezone indicating the timestamp of the event
      - `event` string, required — A string indicating the type of the event
      - `recipients` string[], required — The recipients of the email
      - `subject` string, required — The subject of the email
      - `username` string, required — The username used to send the email
      - `reply_to` string, required — The value of the Reply-To header if present
      - `sender` string, required — The From header of the email
      - `sender_full` string, required — The From header of the email including name part if present
      - `to` string, required — The value of the TO header
      - `cc` string, required — The value of the CC header
      - `bcc` string, required — The value of the BCC header
      - `smtp_response` string, required — The SMTP response of the mail server
      - `reason` string, required — The reason for an event occurring if present
      - `host` string, required — The IP address of the host associated with the event
      - `originating_host` string — The originating IP address of the host associated with the processed event
      - `error` string, required — The error message that occurred on certain events
      - `email_client` object, required — Email client information
      - `metadata` object, required — Additional metadata for open/click events
      - `outbound_ip` string, required — The Outbound IP Address if available
      - `byte_size` integer, required — The size of the email in bytes
      - `headers` string, required — The full email headers if requested
      - `custom_headers` object, required — An dictionary of key/value pairs of custom headers
      - `delivery_attempts` object[] — A list of current delivery attempts if available (for processed events only)
        - `smtptime` string — An RFC3339 encoded timestamp with UTC timezone indicating the timestamp of the delivery attempt
        - `host` string — The host that generated the delivery attempt
        - `smtpresponse` string — The SMTP response from the target server
    - `total_events` integer, required — The total events available to be returned.<br>The actual number of events returned will depend on the number available and the 'limit' passed.
  - `request_id` string, required

## Other responses

- `400` — 400

---

[API](https://skmtc.net/smtp2go/apis/smtp2go-api-v3-0-4.md) · [All operations](https://skmtc.net/smtp2go/apis/smtp2go-api-v3-0-4/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smtp2go/smtp2go-api-v3-0-4/versions/1ba6b25eebb9/schema)