Powerful search for sent Email

The email/search endpoint https://api.smtp2go.com/v3/email/search offers powerful search across your sent email.

This guide will walk you through using the filter_query field to create complex filters to make your searching more efficient. Using this POST, you can retrieve a list of up to 5,000 sent emails matching the supplied parameters. What's more, we'll cover the continue_token, used in this and other endpoints.

📘

Note

Allow around two minutes after delivery for recently sent emails to be included in a search result.

Start with simple filter

The /email/search endpoint allows you to search sent email by date, status, as well as simple or phase based queries.

The /email/send endpoint accepts 12 parameters. Find full details of the parameters below, but note that we'll only make use of a handful in this guide.

👍

No required parameters

Note that not including one or more of the parameters will return all sent emails, by using the defaults detailed below.

A Simple Example

We'll POST to the https://api.smtp2go.com/v3/email/search endpoint, find an example below. For our first search, we'll use the defaults for several parameters, along with the start_date parameter.

Set up your headers.

Be sure to include the content type and your API Key in your header, and all requests going forward.

Set up your data

Though this guide uses cURL for examples, a wide number of options from C++, to Javascript, Node and more can be accessed throughout our API Reference Documentation. Here we include the default values for limit, status, opened, clicked, ignore, filter and headers parameters, as well as a ISO860 Format date-time in our "start_date" variable.

We're looking for all sent emails since the provided date.

📘

Defaults are for demonstration purposes

There's no need to explicitly state the default values as seen in the below example. They are provided for clarity only.

curl --request POST \
     --url https://api.smtp2go.com/v3/email/search \
     --header 'Content-Type: application/json' \
     --header 'X-Smtp2go-Api-Key: api-4A0C6DC6A06D11EDBB65F23C91C88F4E' \
     --header 'accept: application/json' \
     --data '
{
  "limit": 5000,
  "status_counts": false,
  "opened_only": false,
  "clicked_only": false,
  "ignore_case": false,
  "filter_query": "null",
  "headers": [
    "[]"
  ],
  "start_date": "20230403T000000Z"
}
'

Look out for your response.

👍

Success - a 200 OK

The response body of a successful request offers a detailed look at each of the relevant sent emails. First you'll note a request_id and count of valid finds.

• request_id (string)
• count (integer)

For each email, find:

• sender (string)
• email_id (string)
• smtpcode (integer)
• response (string)
• process_status (string)
• host (string)
• recipient (string)
• delivered_at (string)

For each of the opens for that email, find:

• user_agent (string)
• opened_at (string)
• read_secs (string)
• recipient (string)
• ip_address (string)
• total_opens (integer)
• status (string)
• email_ts (string)

Should your search return more than 5,000 results:

• continue_token string

Here's an example 200 response from the request detailed above.

{
  "request_id": "ab4f0236-d2a6-11ed-9255-f23c9216ce11",
  "data": {
    "count": 2,
    "emails": [
      {
        "subject": "My Test Email",
        "delivered_at": "2023-04-04 03:32:09.047010+00:00",
        "process_status": "processing",
        "email_id": "1pjXOz-9EGeSN-09",
        "status": "Submission",
        "response": null,
        "email_ts": "2023-04-04 03:32:09.001800+00:00",
        "host": "localhost",
        "smtpcode": null,
        "sender": "[email protected]",
        "recipient": null,
        "username": "api-xxxxxxx",
        "headers": [
          {
            "key": "[]",
            "value": "Unavailable"
          }
        ],
        "total_opens": 0,
        "opens": [],
        "total_clicks": 0,
        "clicks": []
      },
      {
        "subject": "My Test Email",
        "delivered_at": "2023-04-04 03:32:09.115148+00:00",
        "process_status": "completed",
        "email_id": "1pjXOz-9EGeSN-09",
        "status": "Refused ",
        "email_ts": "2023-04-04 03:32:09.001800+00:00",
        "host": "smtp2go.com",
        "smtpcode": xxx,
        "sender": "[email protected]",
        "recipient": "[email protected]",
        "username": "api-xxxxxx",
        "headers": [
          {
            "key": "[]",
            "value": "Unavailable"
          }
        ],
        "total_opens": 0,
        "opens": [],
        "total_clicks": 0,
        "clicks": []
      }
    ],
    "continue_token": null
  }
}

Here's an example error response, details of which will vary based on the code and error:

{
  "request_id": "22e5acba-43bf-11e6-ae42-408d5cce2644",
  "data": {
    "error_code": "E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED",
    "error": "You do not have permission to access this API endpoint"
  }
}

Explore complex filters

The filter_query field makes use of Whoosh API; a fast, full-text indexing and searching library. You can use it to create complex filters to make searching more efficient.

We can search for a single word (Single Term) or group of words (Phrase) within the email record fields.

📘

Single Terms and Phrases

A Single Term is a single word such as "test" or "hello".
A Phrase is a group of words surrounded by double quotes such as "hello dolly".

Multiple terms can be combined together with Boolean operators to form a more complex query; the API supports boolean operators like AND, OR, and NOT. For full details of the available operators, and much more about the Whoosh API - head to their support docs.

The following fields are indexed and can be used for search:

Construct a search

To search a specific field, use the field name followed by a colon and followed by your Single Term or Phrase.

Subject-line Search

Here's a simple example, which will search messages that contain 'welcome' or 'bienvenidos' in the subject line.

subject:welcome OR subject:bienvenidos

Header Search

Any email header can be searched. The search must be exact, as part matches won't be returned, and we need to ensure the Phrase is surrounded by single quotes.

headers:'X-ExampleCustomHeader: Exact String to Match'

In order to search for multiple headers you must separate the header searches with a semi-colon character.

headers:'X-ExampleCustomHeader: Exact String to Match; X-OfficeId: headquarters;'

Using the Continue Token

When you receive a successful request to your search, you might note the inclusion of a continue_token field. When a string is returned with the continue_token field, it indicates that results exceeding the limit (either passed in the request, or the default value) are available.

In the example at the top of this guide, we noted a maximum of 5,000 results. If we'd seen a value against the continue_token field, we'd know there were more than 5,000 matching emails. In this case:

• The first 5,000 items would be returned
• The continue_token field would contain a string
• In order to retrieve the next batch of results; you can pass this string, along with all of the original request data to continue the search and retrieve the next batch of results.
• In the event of multiple batches, the continue_token will change for each request, so be sure the latest one should always be passed, otherwise you will continue to receive the same batch of results!