1. Data Model & Architecture
Q: Can you provide a data model or ER diagram for the tables we need to ingest?
A: The public Analytics API exposes a single dataset via GET /data_api/v1/emails. The response schema documented in our API reference represents the complete extractable data model, which can be conceptualized as:
- emails (fact table): One row per email analytics record, containing all documented response fields
- email_tags (optional child table): Derived by flattening the tags[] array (0 to n tags per email)
Relationship: emails (1) → (0..n) email_tags
2. Data Transfer & Extraction Methods
Q: Does the application support automated data delivery to AWS S3, bulk export, or streaming APIs?
A: Data access is pull-based via REST API only:
- Automated S3 delivery: Not supported
- Bulk export/extraction API: Not available
- Streaming or GraphQL: Not available
Q: Is there a REST API endpoint or official Python connector available?
A: Yes. The Analytics API is a RESTful API that supports programmatic data extraction. While there is no official SDK or Python connector, the documentation includes example requests (including Python-style examples). Integrations should use standard HTTP clients. Custom Tableau or Python connectors can be built directly against the REST endpoint.
3. Authentication
Q: Which authentication modes are supported?
A: Authentication uses API key-based authorization with a Bearer token in the Authorization header. OAuth (1.0 or 2.0) is not supported for this API. See documentation for implementation details.
4. Rate Limits & Quotas
Q: What are the rate limits for the data extraction endpoint?
A: The Analytics API includes server-side rate limiting to protect stability, though specific numeric limits are not publicly documented. We recommend:
- Conservative pacing: ~100 requests per hour for production workloads
- Implementing pagination with appropriate delays
- Adding exponential backoff and retry logic for non-2xx responses
- Rate limiting is enforced at the API token level
For high-volume or near-real-time sync requirements, coordination with our Engineering team is recommended to establish appropriate patterns. Please contact Support with any specific questions about this.
5. Metadata & Schema Discovery
Q: Is there a metadata API for programmatic retrieval of objects and fields?
A: No separate metadata or schema discovery API is available. The authoritative source is the response schema and examples provided in the /emails endpoint documentation. If needed, this schema can be converted into a data dictionary (e.g., Excel) directly from the documented response fields.
6. Incremental Sync & Pagination
Q: Are filter parameters supported for incremental data pulls (e.g., updated_after, sent_after)?
A: The current API supports page and per_page parameters for pagination. Date-based filtering is on our roadmap for future consideration.
Q: Is sorting by timestamp supported for safe pagination and incremental loads?
A: Yes. Records are returned sorted by sent_at in descending order (most recent first), providing consistent ordering across all pagination requests.
Q: What field serves as the stable unique primary key for deduplication and upsert logic?
A: The current response schema focuses on campaign analytics data. For deduplication, we recommend using a composite key combining subject + sent_at + sent_from.
Q: Is pagination order guaranteed to be consistent across requests?
A: Yes. Pagination uses consistent sent_at DESC ordering, ensuring reliable page traversal across all requests.
7. Pagination Limits
Q: What are the pagination parameters and maximum limits?
A: The /emails endpoint supports:
- per_page: Defaults to 10 records
- Maximum per_page: 100 records (balances response size with efficiency)
8. Data Changes & Update Behaviour
Q: Can email records be updated after initial creation?
A: Yes. Campaign statistics (opens, clicks, read times, survey responses) update continuously as recipient engagement occurs.
Q: Which timestamp reliably reflects updates?
A: Currently, the API returns sent_at, which indicates when the campaign was sent. We're exploring options to expose additional timestamps (such as updated_at) in a future version.
Q: Are tag changes included in updates?
A: Yes. Tags are fetched in real-time, so any modifications to campaign tags are immediately reflected in API responses.
Q: Are deletions possible? If so, is there a tombstone flag or separate endpoint to detect deleted records?
A: Campaigns can be soft-deleted by users. Deleted campaigns are automatically excluded from API responses. There is no separate tombstone mechanism or deletion endpoint.
Q: Is the API eventually consistent? Should we expect late-arriving updates?
A: The API uses a read replica for optimal performance. In practice, data is typically consistent within seconds, though brief delays are possible during high-traffic periods.
9. Data Model & Schema Details
Q: Are there nested objects or arrays besides tags[] that we should account for?
A: The tags[] array (containing name and color properties) is the only nested structure. All other fields are scalar values, keeping the schema straightforward for parsing and storage.
Q: Are tags guaranteed to be unique per email?
A: Tags are managed through a flexible tagging system. While duplicate tag names are uncommon in practice, your integration should handle this possibility.
Q: Can tags change after initial send?
A: Yes. Tags can be added, removed, or modified at any time, providing flexibility in campaign organization.
10. Data Volume & Constraints
Q: What is the typical and maximum volume of email analytics records per customer?
A: Volume varies based on usage patterns and scales with send frequency and recipient counts. The API is designed to handle customers with extensive campaign histories.
Q: Are there maximum lookback windows or query constraints (e.g., last 90 days only)?
A: No. There are no date range restrictions. The API returns all sent campaigns, providing access to complete historical data.