Understand the flow
Historical sync performs a bounded backfill of mailbox data for a single account. The job runs in batches to avoid API rate limits and records progress checkpoints that you can query later. Before triggering anything, align on the size of the window you want to import and whether you need to pause real-time syncing while the backfill completes.
Historical sync is idempotent and can run alongside realtime sync. The backfill simply fills any historical gaps that may exist before realtime events pick up new activity.
Configure the sync window
Edit riposte/sync.config.json to dial in the cadence. You can tune the maximum time range, the number of concurrent accounts, and the delay between batches. These settings are shared across all accounts, so make sure they line up with your throughput requirements.
Checklist
- Decide how far back to pull messages (timeRangeDays)
- Confirm batch sizes that will not exhaust provider quotas
- Record the defaults so you can restore them later
Changes are tracked alongside source control. Update default, global, or an environment override and redeploy or reload the service to pick up new settings.
Kick off the job
When you are ready, call the start endpoint with the account identifier. The response returns immediately so that you can enqueue multiple accounts. Riposte will handle deduping work if a job is already running.
If you call the start endpoint repeatedly with the same account we will reuse the running job. You do not need custom guards in your orchestration layer.
Track progress
Poll the progress endpoint or subscribe to historical sync events via webhooks to understand how much data remains. The progress response includes counts for processed messages, batch state, and timestamps for the last completed window.
Polling works well for small accounts. For larger imports configure a webhook endpoint so you receive completion notifications without hammering the API.
Troubleshoot failures
Failures are rare but can happen due to upstream throttling or unexpected data edge cases. When that happens, Riposte will pause the job and emit detailed logs. Inspect the state field on the progress response and review the logs or webhook delivery payload for remediation steps.
If progress reports that a batch is permanently failed, clear the failure flag before re-triggering the job. This ensures we do not immediately short-circuit the next attempt.