Trendtrack
ReferenceAPI

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.

keywordMode?string

How multiple search keywords are combined. Allowed values: 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.

page?number
limit?number
sentAfter?string
sentBefore?string
campaignTypes?array<string>

Stored campaign type names, matched case-insensitively: Welcome and Abandoned Cart (the automated flows), Newsletter, Marketing.

languages?array<string>
promotionTypes?array<string>

Stored promotion type names, matched case-insensitively (Discount %, Discount % With Threshold, Free Delivery, BOGO, Bundle Deal, No Promotion, …).

promotionTypeIds?array<number>
categories?array<string>

Stored email category names, matched case-insensitively (Promotional Campaign, Product Campaign, Launch Campaign, Relational Campaign, Event Campaign, Win-back Campaign, Survey).

emailCategoryIds?array<number>
eventNames?array<string>
eventIds?array<number>
eventCategories?array<string>
minBodyLength?number
maxBodyLength?number
shopIds?array<string>

Stable public shop identifiers.

minMonthlyVisits?number
maxMonthlyVisits?number
trafficGrowth?string

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

minProductsCount?number
maxProductsCount?number
creationCountries?array<string>
excludeCreationCountries?array<string>
currencies?array<string>
shopDefaultLanguages?array<string>
mainMarketCountries?array<string>
amongMarketCountries?array<string>
excludeMarketCountries?array<string>
visitorCountries?array<string>

Alias of amongMarketCountries: matches shops with any of these countries among their markets. No separate visitor-country data is indexed.

shopCreatedAfter?string
shopCreatedBefore?string
technologies?array<string>

Main e-commerce platform slugs or ids (shopify, woocommerce, wordpress, magento, wix, …). Only the shop's main platform is indexed for emails; other technologies are rejected with unsupported_filter.

shopifyPlan?string

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

categoryIds?array<number>
minShopEmails90d?number
maxShopEmails90d?number
minAvgEmailsPerWeek?number
maxAvgEmailsPerWeek?number
minActiveAds?number
maxActiveAds?number
adsGrowth?string

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

minTrustpilotRating?number
maxTrustpilotRating?number
minTrustpilotReviewCount?number
maxTrustpilotReviewCount?number

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/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": 1,        "category": "Promotional Campaign",        "categoryId": 4,        "event": {          "name": "Black Friday",          "id": 1,          "category": "Commercial Events"        }      },      "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"          ]        }      ]    }  }}

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

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"          ]        }      ]    }  }}

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

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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": 1,      "category": "Promotional Campaign",      "categoryId": 4,      "event": {        "name": "Black Friday",        "id": 1,        "category": "Commercial Events"      }    },    "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": "04504d0b-df46-4f62-98b6-d4d9e14a2282",        "mainTechnologySlug": "shopify",        "mainTechnologyName": "Shopify"      },      "trustpilot": {        "rating": 4.6,        "reviewCount": 1834      },      "analytics": {        "campaignTypes": {          "Marketing": 75,          "Newsletter": 25        },        "categoryTypes": {          "Promotional Campaign": 28,          "Product Campaign": 2        },        "emailsByDayOfWeek": {          "0": 3,          "1": 2,          "3": 5,          "6": 8        }      }    },    "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"          ]        }      ]    }  }}

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.

sentAfter?string
sentBefore?string
campaignTypes?array<string>

Stored campaign type names, matched case-insensitively: Welcome and Abandoned Cart (the automated flows), Newsletter, Marketing.

languages?array<string>
page?integer
limit?integer

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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": 1,        "category": "Promotional Campaign",        "categoryId": 4,        "event": {          "name": "Black Friday",          "id": 1,          "category": "Commercial Events"        }      },      "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"          ]        }      ]    }  }}

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/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"          ]        }      ]    }  }}