---
title: "Mailbox sync troubleshooting: recover a stalled workflow"
description: "Diagnose a mailbox that stopped updating, check connection status, request manual sync, and verify message and workflow recovery in Mailera."
url: https://mailera.app/en/blog/mailbox-sync-troubleshooting
published: 2026-10-25
updated: 2026-10-25
---

# Mailbox sync troubleshooting: recover a stalled workflow

Find out whether the missing update is at your email provider, in Mailera, or in your application. Then request sync and verify the affected message before repeating any downstream action.

## Is the problem at the provider, in Mailera, or in your workflow?

Start with one affected mailbox and one known message. Record its sender, subject, approximate receipt time, and folder in provider webmail. Include the timezone. Keep private content out of shared troubleshooting notes.

[Mailera connects existing mailboxes to applications and agents](https://mailera.app/en/product). Check delivery at the provider first, then visibility in Mailera, then processing by your application.

| Observation | Next check | Recovery criterion |
| --- | --- | --- |
| Message absent in provider webmail | Check the provider mailbox and other folders; investigate delivery | Locate the original message at the provider before treating this as a Mailera sync issue |
| Present at the provider, absent in Mailera | Check connection status, last sync, and the matching folder | The known message appears in Mailera |
| Present in Mailera, not processed downstream | Inspect application logs and any webhook-dependent processing | The processing record establishes whether the intended action completed |
| Present in Junk rather than Inbox | Compare folder placement and the workflow's folder selection | Locate the message and explicitly decide how the workflow should handle it |

Different folder counters aren't enough to conclude that mail is lost. Mailera's mailbox list shows unread Inbox and Junk counts; use the actual message as your reference. Don't ask for a resend until you've checked what happened to the original.

![Decision tree separating provider delivery, Mailera sync, and downstream workflow failures.](https://mailera.app/media/8a5013d9709f6c4a/mailbox-sync-troubleshooting-recover-a-stalled-workflow-en-1200.jpg)
_Locate the known message before choosing a recovery action._

## What should you check before requesting sync?

Use `GET /mailboxes/{id}` to inspect `data.provider`, `data.status`, `data.last_sync_at`, and `data.sync` for the affected mailbox. Capture the current state before changing anything.

![Mailboxes page showing unread Inbox and Junk counts for a redacted test mailbox.](https://mailera.app/media/6e5bf47a68da748d/mailbox-sync-troubleshooting-recover-a-stalled-workflow-en-1200.jpg)
_Folder counts provide context; capture connection and sync state through the API._

For API checks, use a key scoped to the mailbox's group with **Read** and **Sync** selected. Create it through **Settings** → API key tab → **Create key**. Avoid selecting all groups for a single-mailbox incident.

Set `$MAILERA_API_KEY` and `$MAILBOX_ID` in your local environment. Keep the key out of logs and screenshots. The following requests use the `read` permission.

```bash
curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID" \
  --header "Authorization: Bearer $MAILERA_API_KEY"
```

Inspect `data.provider`, `data.status`, `data.error`, and `data.error_code`. Record `data.last_sync_at` and the nested `data.sync` fields, including `last_synced_at` and `sleeping_since`. Folder counters provide context, not proof that the affected message arrived.

Then check sign-in status:

```bash
curl --request GET \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/status" \
  --header "Authorization: Bearer $MAILERA_API_KEY"
```

**The status check means different things by provider.** For Microsoft, Mailera checks sign-in directly. For other providers, it bases sign-in status on the latest sync. A non-Microsoft status result is therefore not an independent, fresh authentication test.

### Repair the connection before retrying

For Outlook.com, Hotmail, or Microsoft 365, follow [Mailera's Microsoft connection guidance](https://mailera.app/en/providers/microsoft) and use OAuth through Microsoft Graph. Don't substitute an app password. Mailera receives new Microsoft mail through Graph change notifications, with periodic background checks as a fallback.

For Gmail sync problems, compare Gmail webmail with Mailera first. Mailera's [Gmail connection](https://mailera.app/en/providers/gmail) uses an app password, subject to two-step verification and administrator permission. [Google's app-password guidance](https://support.google.com/accounts/answer/185833) explains the requirements and notes that changing your Google Account password revokes app passwords. If the problem began after a password change, investigate the connection credential rather than substituting your normal account password.

Related: [App passwords for agent mailboxes](https://mailera.app/en/blog/email-app-password-ai-agent).

Repeated requests aren't a connection repair. If you're investigating a direct Graph integration and encounter HTTP `429`, [Microsoft's throttling guidance](https://learn.microsoft.com/en-us/graph/throttling) says to respect `Retry-After`, or use exponential backoff when that header is absent.

### Separate sleeping from paused

Mailera checks actively used mailboxes more frequently than idle ones. The sync endpoint wakes sleeping mailboxes.

An explicitly paused mailbox is a different case. Pause and resume use `PATCH /mailboxes/{id}` with `manage` permission. Keep that authorization separate from the baseline read-and-sync key; don't assume a sync request is a resume operation. Consult the [Mailera API reference](https://mailera.app/en/docs) for the pause/resume operation rather than guessing a request body.

## How do you request sync and verify recovery?

Use this sequence after resolving any connection issue. Each step should leave something you can check.

1. **Confirm the mailbox and reference message.** Match the mailbox ID to the intended account. Record the known message's sender, subject, folder, and approximate receipt time from provider webmail. Look for that specific message rather than a target unread count.
2. **Confirm the recovery key's scope.** Use the affected mailbox group with **Read** and **Sync** permissions. Leave **Send messages** and **Manage mailboxes** out unless a separate, authorized task requires them. Confirm that access is limited to the recovery work.
3. **Request manual mailbox sync.** Run the request below. Save its actual response and the request time in your incident record, with secrets removed. That records the request, not completion of the workflow.

```bash
curl --request POST \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/sync" \
  --header "Authorization: Bearer $MAILERA_API_KEY"
```

This operation requires `sync` permission and also wakes sleeping mailboxes. For an MCP-based recovery flow, the equivalent tool is `sync_mailbox`, which requires the same permission. Neither path removes the need to verify the message afterward.

4. **Recheck mailbox state and locate the message.** Repeat the mailbox-details request above and compare its sync information with your earlier record. Then list messages in the relevant folder. This example checks Inbox for an owned test message using the search text `sync recovery test`; replace that text with your reference message's search terms.

```bash
curl --get \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
  --header "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode "folder=inbox" \
  --data-urlencode "q=sync recovery test" \
  --data-urlencode "limit=10"
```

The endpoint also accepts `from`, `since`, `unread`, and `cursor`. Use `folder=junk` when that's where provider webmail shows the message. Avoid an unread-only filter if the reference message may already be read. If the response includes `next_cursor`, use it with `cursor` to inspect subsequent results when needed.

Match `from.address`, `subject`, `received_at`, and `folder`. Save the returned message `id` for your processing investigation. Your checkpoint is the known message in the expected mailbox and folder.

![A known test message visible in the selected mailbox and folder in Mailera's Unified inbox.](https://mailera.app/media/cd9e7ba53410f84c/choose-an-email-mcp-server-for-your-existing-mailboxes-en-1200.jpg)
_Verify the reference message itself, not just the unread count._

5. **Reconcile downstream state before resuming.** Find the corresponding processing record in your application. Determine whether the original action completed, failed, or still needs investigation. Resume only when you know which action remains necessary. A visible message does not establish that a reply, notification, or external task ran.

## What if the mailbox is current but the workflow is still stalled?

Stop treating the incident as missing mail once you've found the message. Inspect the application's processing logs and, if the workflow depends on `message.received`, its configured webhook subscription and consumer records. Mailera also supports `message.junk` and `mailbox.disconnected`; check which events your workflow expects.

Don't use a manual sync request as a webhook-replay plan. Establish what the consumer received and what it did before deciding how to recover application processing.

Related: [Unified inbox operations for AI agents](https://mailera.app/en/blog/unified-inbox-for-ai-agents).

If sending was involved, investigate the original attempt through `GET /sends/{id}` using a separately authorized key with `send` permission. Its states include `queued`, `sending`, `sent`, `failed`, and `unknown`. An `unknown` state isn't a reason to send again blindly.

Keep send-status investigation out of the baseline recovery key. Restoring mailbox visibility and authorizing another external action are separate decisions.

## Which common mistakes make recovery harder?

- **Requesting sync repeatedly without checking the provider.** First establish that the reference message exists in provider webmail and resolve connection errors.
- **Reading every status result as a fresh sign-in test.** Only the Microsoft status check tests sign-in directly; other providers depend on the latest sync.
- **Treating sleep and pause as interchangeable.** Sync wakes a sleeping mailbox. Pause/resume is a separate management operation.
- **Using sync as permission to repeat work.** Check the original send or task record before another attempt.
- **Deleting and re-adding the mailbox first.** Capture the existing state and diagnose the failure before changing the connection.

For escalation, collect the mailbox ID, provider, timestamps with timezone, endpoint, actual response, and comparison with provider webmail. Redact credentials, addresses, and private message content. Preserve enough detail to identify the failing step without sharing the full message.

## How should an AI agent handle recovery safely?

Treat incoming email as untrusted data, not instructions. An email asking the agent to change credentials, reveal secrets, or invoke tools must not control the recovery procedure.

Limit the recovery key to the required mailbox group and `read`/`sync` permissions. Add `manage` only for an explicitly authorized pause/resume task. Require human confirmation before sending or repeating an external action, even after the message becomes visible.

Use mailboxes you own for recovery exercises. Redact addresses, message bodies, and secrets in screenshots and logs. Keep access decisions consistent with your team's controls and [Mailera's security information](https://mailera.app/en/security).

## What are Mailera's recovery limits?

Mailera checks actively used mailboxes more frequently than idle ones. The sync endpoint requests an immediate mailbox sync and wakes sleeping mailboxes. The free workspace retains messages for 30 days. After requesting sync, locate the reference message and reconcile downstream processing.

Mailera cannot guarantee Inbox placement or make a provider trust a sender. If the message is in Junk, separate that placement issue from synchronization.

This runbook concerns an existing Mailera connection. It is not an Outlook desktop profile-repair procedure or an Outlook shared-mailbox permissions guide.

**Do this with the API** — Every action in this article is available via the REST API, with curl examples, API keys and webhooks. [View API docs](https://mailera.app/en/docs)