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
POST /api/sync
Content-Type: application/json
Request body
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | No | IMAP account to sync. Omit to sync the primary account |
Response
{
"success": true,
"accountId": "acc_0x9f2c",
"status": "synced",
"newMessages": 4,
"syncedAt": "2025-06-14T11:05:30Z"
}status is "synced" when the sync ran immediately, or "queued" when the server is already processing a sync for this account and the request was deduplicated.
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
GET /api/sync
Returns the current sync state for all connected accounts.
Response
{
"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.
Example: refresh button handler
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
}
}