Email Sync
Trigger manual IMAP sync for connected email accounts to fetch latest messages
MisarMail automatically syncs connected IMAP accounts every 5 minutes. The sync API lets you trigger an immediate sync on demand — for example, when a user clicks a "Refresh" button in your inbox UI.
Requires active session (dashboard only).
Trigger a sync
/api/syncTrigger an immediate sync for a connected IMAP account.
Request body
account_idstringbodyIMAP account to sync. Omit to sync the primary account.
Response fields
successbooleantrue when the request succeeded.
accountIdstringThe account that was synced.
statusstring"synced" when the sync ran immediately, or "queued" when the server is already processing a sync for this account and the request was deduplicated.
newMessagesnumberNumber of new messages fetched.
syncedAtstringISO-8601 timestamp of the sync.
curl -X POST /api/sync \
-H "Content-Type: application/json" \
-d '{ "account_id": "acc_0x9f2c" }'async function handleRefreshClick(accountId: string) {
const res = await fetch('/api/sync', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ account_id: accountId }),
});
const { status, newMessages } = await res.json();
if (status === 'synced' && newMessages > 0) {
// reload inbox list
}
}{
"success": true,
"accountId": "acc_0x9f2c",
"status": "synced",
"newMessages": 4,
"syncedAt": "2025-06-14T11:05:30Z"
}Throttling
Sync requests for the same account are throttled to one per 30 seconds. If you trigger a sync within 30 seconds of the last one, the API returns the previous sync result instead of re-running — status will be "queued" in this case.
Do not poll this endpoint. Use it only in response to an explicit user action (e.g. a refresh button click). Background polling will exhaust the throttle window and prevent timely syncs.
Get sync status
/api/syncReturns the current sync state for all connected accounts.
Response fields
accountsArray<object>Connected accounts, each with id, email, lastSyncAt, syncStatus, and newMessageCount.
{
"accounts": [
{
"id": "acc_0x9f2c",
"email": "[email protected]",
"lastSyncAt": "2025-06-14T11:05:30Z",
"syncStatus": "idle",
"newMessageCount": 0
},
{
"id": "acc_0xb31a",
"email": "[email protected]",
"lastSyncAt": "2025-06-14T10:58:12Z",
"syncStatus": "failed",
"newMessageCount": 0
}
]
}syncStatus values:
| Value | Meaning |
|---|---|
idle | Last sync completed successfully, no active sync |
syncing | A sync is currently in progress |
failed | Last sync attempt failed (check IMAP credentials or server availability) |
Auto-sync behaviour
| Trigger | Interval |
|---|---|
| Background auto-sync | Every 5 minutes per account |
Trigger via POST /api/sync | Immediate, throttled to 1 per 30 s |
| New account connected | Sync triggered automatically |
When an account's syncStatus is failed, MisarMail retries with exponential back-off (1 min, 5 min, 15 min) before marking the account as requiring manual intervention.