Historical email backfill

When you connect a Gmail or Microsoft 365 mailbox, Workestra needs to pull your existing email history so threads, contacts, and conversations are immediately useful — not just mail that arrives going forward. The backfill is the job that does that.

This page explains how to choose a range, what to expect during the sync, and how to troubleshoot if something looks wrong.

The range picker

Right after you connect your mailbox, a dialog asks:

How much mail should we sync?

You pick one of four ranges:

You can skip the picker by clicking Skip for now. No history is pulled, and only new mail going forward will appear. You can always trigger a backfill later — see Starting a backfill later.

Watching progress

After you pick a range, a progress card appears on your connection in Settings → Integrations → Outlook (or Gmail). It updates live — you don't need to refresh.

📥 Syncing last 90 days
████████████████░░░░░░  3,247 of ~8,500 messages
~4 minutes remaining                  [Pause] [✕]

The card shows:

• Progress bar — how far through the backfill you are.
• Message count — how many messages have been pulled, and an estimate of the total.
• ETA — appears after the first minute or so, once we have a stable rate.
• Pause — stop the sync cleanly. You can resume later with no loss.
• Cancel (✕) — stop for good. Messages already pulled stay in Workestra.

You don't have to watch — you can close the tab, navigate elsewhere, or keep using Workestra. The sync runs in the background on our servers, not your browser.

Pause, resume, cancel

All three actions are on the progress card.

Pause

Stops the sync cleanly at the end of the current page. The progress bar turns amber and the card flips to Paused. Useful when:

• You're on a shared Wi-Fi that's rate-limited or unreliable.
• You want to reduce load while you're in an all-day video call.
• You accidentally picked Everything on a huge mailbox and want to switch later.

Resume

The same button, now showing Resume. Picks up exactly where you left off — we store the cursor every page, so no duplicate fetches and no missed messages.

Cancel

Stops the sync permanently. The connection transitions to Healthy (for the portion already synced) and new mail from the real-time webhook continues to flow in. Messages already pulled during the partial backfill stay — cancelling doesn't delete anything.

What the backfill pulls

• Your Inbox — all folders flagged as Inbox by your provider. Most users have one.
• Your Sent folder — so when you open a CRM contact's page, you see both sides of the conversation.

Messages are deduplicated by provider message id, so if you pause, resume, or reconnect, you won't get duplicate rows.

What the backfill does NOT pull

• Messages older than your chosen range.
• Messages permanently deleted from your provider.
• Drafts.
• Other folders (Archive, custom labels, sub-folders). Only Inbox and Sent today.
• Attachments — Workestra stores attachment metadata (filename, size, type) but not the binary content. Clicking an attachment still takes you to the provider to download.

If you need something not on this list, let us know — some are on the roadmap and some are intentionally out of scope.

Handoff to real-time sync

When the backfill finishes, Workestra automatically switches to real-time mode:

1. The backfill writes the final delta cursor to your connection.
2. The webhook subscription (if it wasn't already active) is registered with Microsoft Graph.
3. From that point on, new mail arrives within seconds of landing in your mailbox.

You'll see the progress card flip to a green Sync complete — 3,247 messages from last 90 days banner, which fades into the standard Healthy status after a short delay.

Starting a backfill later

If you skipped the range picker or want more history than you originally chose, you have two options:

Option 1: Disconnect and reconnect

1. Go to Settings → Integrations → Outlook
2. Click the trash icon on your connection, confirm
3. Click Connect and go through the OAuth flow again
4. The range picker appears — pick your new range

All previously synced messages are preserved during reconnect — only the OAuth token record is recreated.

Option 2: Ask support

For very large mailboxes where Option 1 is inconvenient (e.g. you'd lose a 2-hour partial sync), contact support and ask for a "backfill reset" with a specific range. We can trigger it server-side without making you disconnect.

Troubleshooting

Progress seems stuck

Look at the "X of ~Y messages" count. If it changed recently (within the last 2 minutes), the sync is working — the bar might just be moving slowly because we're on a dense portion of the mailbox (e.g. a week with many newsletters).

If the count hasn't moved for more than 5 minutes:

• Check the connection health badge. If it's Error, the token or mailbox has a problem — reconnect.
• Click Pause, wait 10 seconds, click Resume. This nudges our cron to pick up the connection immediately.
• If that doesn't help, cancel and start a new backfill.

Backfill shows a red "Failed" state

The connection card will show the specific error. Common causes:

• Token expired — reconnect your account.
• Throttled by Microsoft — this is automatic and temporary. Workestra retries on the next cron tick (hourly). You don't have to do anything, but clicking Retry on the card speeds things up.
• Permission lost — Exchange admin may have revoked access, or for shared mailboxes, the "Full Access" grant was removed. Contact your admin.

My mailbox is huge and I don't want to wait hours

Pick a smaller range first. Once Workestra has your recent 30 or 90 days, it's usable for most workflows. You can come back later and run Everything when you have time.

I see "Waiting on personal@acme.com — reconnect it" on my shared mailbox

Shared mailboxes borrow their permission from a personal Outlook connection. If that personal connection fails, all its shared mailbox children stop syncing. Reconnect the personal account and the shared mailboxes resume automatically.

Why a separate backfill, not just "fetch everything"?

Two reasons:

1. Speed to value. Most users want to be useful in Workestra within a minute of connecting. The range picker lets you trade latency for completeness. 90 days is plenty for almost every sales/support workflow.

2. Reliability. Running a multi-hour sync in a single request is fragile — any network hiccup, server restart, or provider throttle cancels the whole thing. The backfill is designed as thousands of small, resumable steps, so it always finishes eventually even under adverse conditions.

Next Steps

• Microsoft 365 Integration — Full Outlook connection guide
• Shared Mailboxes — Delegating access to support@, sales@, etc.
• Email in your modules — How mail surfaces on CRM, Support, and Recruiting pages
• Inbox — Unified destination for email + notifications