Mailbox sync troubleshooting: recover a stalled workflow

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. Check delivery at the provider first, then visibility in Mailera, then processing by your application.

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.

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.

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.

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:

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 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 uses an app password, subject to two-step verification and administrator permission. Google's app-password guidance 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.

Repeated requests aren't a connection repair. If you're investigating a direct Graph integration and encounter HTTP 429, Microsoft's throttling guidance 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 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.

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.

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.

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.

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.

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.