Emails

Query emails

Returns the advanced public emails discovery surface. This endpoint is the canonical public route for richer email filters while keeping the response aligned with the stable public EmailSummary contract. The API does not expose opens, clicks, conversions, or revenue metrics; sorting is discovery-oriented metadata ordering, not best-performance scoring.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

search?array<string>

searchType?string

Search mode for this request. Allowed values: domain, email, shopKeywords.

Value in"domain" | "email" | "shopKeywords"

keywordMode?string

How multiple search keywords are combined. Allowed values: any, all.

Value in"any" | "all"

sortBy?string

Sort key for this request. Allowed values: newest, oldest, relevance, monthlyVisits, bodyLength, shopEmailFrequency, event, promotionType. These are discovery/indexing sorts, not opens/clicks/conversions performance rankings.

order?string

Sort direction for this request. Allowed values: asc, desc.

Value in"asc" | "desc"

page?number

Range1 <= value

limit?number

Range1 <= value <= 100

sentAfter?string

Formatdate-time

sentBefore?string

Formatdate-time

campaignTypes?array<string>

languages?array<string>

promotionTypes?array<string>

promotionTypeIds?array<number>

categories?array<string>

emailCategoryIds?array<number>

eventNames?array<string>

eventIds?array<number>

eventCategories?array<string>

minBodyLength?number

Range0 <= value

maxBodyLength?number

Range0 <= value

shopIds?array<string>

Stable public shop identifiers.

minMonthlyVisits?number

Range0 <= value

maxMonthlyVisits?number

Range0 <= value

trafficGrowth?string

Traffic growth filter DSL using public rolling windows. Valid periods: last30d, last90d, last180d.

minProductsCount?number

Range0 <= value

maxProductsCount?number

Range0 <= value

creationCountries?array<string>

excludeCreationCountries?array<string>

currencies?array<string>

shopDefaultLanguages?array<string>

mainMarketCountries?array<string>

amongMarketCountries?array<string>

excludeMarketCountries?array<string>

visitorCountries?array<string>

shopCreatedAfter?string

Formatdate

shopCreatedBefore?string

Formatdate

technologies?array<string>

shopifyPlan?string

Enum value accepted by this request. Allowed values: all, plus, nonPlus.

Value in"all" | "plus" | "nonPlus"

categoryIds?array<number>

minShopEmails90d?number

Range0 <= value

maxShopEmails90d?number

Range0 <= value

minAvgEmailsPerWeek?number

Range0 <= value

maxAvgEmailsPerWeek?number

Range0 <= value

minActiveAds?number

Range0 <= value

maxActiveAds?number

Range0 <= value

adsGrowth?string

Ads growth filter DSL using public rolling windows. Valid periods: last7d, last30d, last90d.

minTrustpilotRating?number

Range0 <= value <= 5

maxTrustpilotRating?number

Range0 <= value <= 5

minTrustpilotReviewCount?number

Range0 <= value

maxTrustpilotReviewCount?number

Range0 <= value

Response Body

`application/json`

curl -X POST "https://api.trendtrack.io/v1/emails/query" \  -H "Content-Type: application/json" \  -d '{    "search": [      "welcome",      "discount"    ],    "searchType": "email",    "keywordMode": "any",    "sortBy": "newest",    "order": "desc",    "minMonthlyVisits": 20000,    "promotionTypes": [      "Discount"    ],    "shopifyPlan": "plus",    "page": 1,    "limit": 25  }'

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": 123456,
      "sentAt": "2026-04-18T12:30:00.000Z",
      "campaignType": "Newsletter",
      "classification": {
        "promotionType": "Discount",
        "promotionTypeId": 4,
        "category": "Promotional",
        "categoryId": 7,
        "event": {
          "name": "Black Friday",
          "id": 12,
          "category": "Sales"
        }
      },
      "content": {
        "subject": "Up to 30% off this weekend",
        "preheader": "Limited-time offers picked for you.",
        "bodyPreview": "Shop limited-time offers picked for you before they are gone.",
        "bodyLength": 428,
        "screenshotUrl": "https://cdn.example.com/emails/123.png"
      },
      "shop": {
        "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
        "domain": "example.com",
        "name": "Example Shop"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get an email by id

Returns one public email detail object by stable email identifier, including the clean public shop context nested under the email.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

emailId*string

Stable public email identifier.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/emails/123456"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "id": 123456,
    "sentAt": "2026-04-18T12:30:00.000Z",
    "campaignType": "Newsletter",
    "classification": {
      "promotionType": "Discount",
      "promotionTypeId": 4,
      "category": "Promotional",
      "categoryId": 7,
      "event": {
        "name": "Black Friday",
        "id": 12,
        "category": "Sales"
      }
    },
    "content": {
      "subject": "Up to 30% off this weekend",
      "preheader": "Limited-time offers picked for you.",
      "bodyPreview": "Shop limited-time offers picked for you before they are gone.",
      "bodyLength": 428,
      "screenshotUrl": "https://cdn.example.com/emails/123.png",
      "body": "Shop the full collection with exclusive offers for this weekend only."
    },
    "shop": {
      "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
      "domain": "example.com",
      "name": "Example Shop",
      "createdAt": "2024-01-15T00:00:00.000Z",
      "profile": {
        "countryCode": "US",
        "currency": "USD",
        "defaultLanguage": "en",
        "mainMarket": "US",
        "isShopifyPlus": true,
        "visitorCountries": [
          "US",
          "CA",
          "GB",
          "FR",
          "DE"
        ]
      },
      "traffic": {
        "monthlyVisits": 45231,
        "growth30d": 0.18,
        "growth90d": 0.27,
        "growth180d": 0.41
      },
      "catalog": {
        "productsCount": 124,
        "categoryIds": [
          166,
          204
        ]
      },
      "marketing": {
        "emailsLast90d": 37,
        "avgEmailsPerWeek": 2.8,
        "activeAds": 14,
        "avgActiveAds7d": 9.2,
        "avgActiveAds30d": 11.6,
        "activeAdsGrowth7d": 0.12,
        "activeAdsGrowth30d": 0.34,
        "activeAdsGrowth90d": 0.58
      },
      "technology": {
        "mainTechnologyId": "tech_klaviyo",
        "mainTechnologySlug": "klaviyo",
        "mainTechnologyName": "Klaviyo"
      },
      "trustpilot": {
        "rating": 4.6,
        "reviewCount": 1834
      },
      "analytics": {
        "campaignTypes": {
          "Newsletter": 12,
          "Marketing": 9
        },
        "categoryTypes": {
          "Promotional": 8,
          "Seasonal": 4
        },
        "emailsByDayOfWeek": {
          "1": 4,
          "3": 7,
          "5": 2
        }
      }
    },
    "language": "english"
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get raw email HTML by id

Returns the raw captured HTML for one public email identifier. Existing emails may have html=null when raw HTML is unavailable.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

emailId*string

Stable public email identifier.

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/emails/123456/html"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "emailId": 123456,
    "html": "<!doctype html><html><body>...</body></html>",
    "htmlLength": 12345
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

List emails for a shop

Returns the paginated public emails linked to one shop identifier, with stable recency-oriented filters and the same public EmailSummary response contract as the global emails surface.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

shopId*string

Stable public shop identifier.

Query Parameters

search?array<string>

Optional email search keywords. Repeated query params and comma-separated values are both accepted.

sortBy?string

Sort key for this request. Allowed values: newest, oldest, relevance, event, promotionType. These are discovery/indexing sorts, not opens/clicks/conversions performance rankings.

Value in"newest" | "oldest" | "relevance" | "event" | "promotionType"

sentAfter?string

Formatdate-time

sentBefore?string

Formatdate-time

campaignTypes?array<string>

languages?array<string>

page?integer

Default1

Range1 <= value

limit?integer

Default25

Range1 <= value <= 100

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/shops/3f8aa146-6f96-46e8-9781-64db5166f9a8/emails"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": [
    {
      "id": 123456,
      "sentAt": "2026-04-18T12:30:00.000Z",
      "campaignType": "Newsletter",
      "classification": {
        "promotionType": "Discount",
        "promotionTypeId": 4,
        "category": "Promotional",
        "categoryId": 7,
        "event": {
          "name": "Black Friday",
          "id": 12,
          "category": "Sales"
        }
      },
      "content": {
        "subject": "Up to 30% off this weekend",
        "preheader": "Limited-time offers picked for you.",
        "bodyPreview": "Shop limited-time offers picked for you before they are gone.",
        "bodyLength": 428,
        "screenshotUrl": "https://cdn.example.com/emails/123.png"
      },
      "shop": {
        "id": "3f8aa146-6f96-46e8-9781-64db5166f9a8",
        "domain": "example.com",
        "name": "Example Shop"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 235,
    "totalPages": 10
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

Get shop email stats

Returns shop-scoped 90-day email frequency stats and sparse UTC calendar counts for one requested month.

Authorization

publicApiBearer

AuthorizationBearer <token>

Provide a Trendtrack Public API key using Authorization: Bearer <api_key>.

In: header

Path Parameters

shopId*string

Stable public shop identifier.

Query Parameters

month*string

Calendar month to aggregate, formatted as YYYY-MM.

Match^\d{4}-(0[1-9]|1[0-2])$

Response Body

`application/json`

curl -X GET "https://api.trendtrack.io/v1/shops/3f8aa146-6f96-46e8-9781-64db5166f9a8/emails/stats?month=2026-04"

{
  "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
  "data": {
    "last90Days": {
      "totalEmails": 37,
      "avgEmailsPerWeek": 2.8,
      "emailsByDayOfWeek": {
        "1": 4,
        "3": 7
      }
    },
    "calendar": {
      "month": "2026-04",
      "totalEmails": 12,
      "emailsByDate": {
        "2026-04-03": 2,
        "2026-04-18": 1
      }
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

{
  "error": {
    "code": "missing_api_key",
    "message": "Provide an API key using Authorization: Bearer <api_key>.",
    "requestId": "5d93d8de-0f6d-46a4-bd10-2e519b7e96bc",
    "details": {
      "validationErrors": [
        {
          "field": "query-string.limit",
          "location": "query-string",
          "expected": [
            "limit must not be greater than 100"
          ]
        }
      ]
    }
  }
}

200application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`