How to bulk unspam email across connected mailboxes

What does bulk unspam actually do?

Here, bulk unspam email means recovering legitimate received messages from Spam or Junk. It isn't a pre-send spam checker, an inbox-placement test, or a guide to sending bulk email.

Mailera connects existing mailboxes, so you can review mail together while retaining each message's mailbox context. The Unified inbox is a shared view; recovery through POST /mailboxes/{id}/unspam targets one mailbox at a time. Your client coordinates the cross-mailbox batch.

Choose the narrowest operation that matches what you approved:

Prefer individual moves when you approved a fixed list. A sender-wide operation is a broader instruction than recovering only the messages you inspected.

What should you check before moving messages?

Use only mailboxes you own or are authorized to operate. In Mailboxes, check connection status and last sync before choosing candidates. Unread Inbox and Junk counts help you locate work, but they aren't an inventory of every message.

Check GET /mailboxes/{id}/status when a connection looks questionable. For Microsoft, it checks sign-in directly; for other providers, its result is based on the latest synchronization. An empty, stale, or disconnected view is not proof that the provider's folder is empty.

If you need connection help, use the Outlook and Microsoft 365 connection page or the Gmail connection page before starting recovery.

Create a key through Settings → API key → Create key. Set Mailbox scope to the relevant group and enable Read plus Move messages. Add Sync only if your workflow needs to request synchronization. Both recovery operations require the move scope; reading candidates requires read.

Keep the credential out of screenshots and outcome logs. The Mailera security page is a useful reference when deciding who should hold the recovery key.

Review message context, not just the sender address. In its Gmail spam guidance, read on 25 October 2026, Google advises against replying or opening links in suspected spoofed mail until the address has been verified. A familiar-looking sender is not enough to approve recovery.

How do you recover messages across several mailboxes?

Start with a mailbox you control as a test. Complete the recovery and verification cycle there before expanding the approved set.

1. Enumerate the authorized mailboxes

Set $MAILERA_API_KEY in your local environment, then list mailboxes:

curl --get 'https://mailera.app/api/public/v1/mailboxes' \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'limit=1' \
  --data-urlencode 'offset=0'

This deliberately small request returns a page, not the whole workspace. Use total, limit, and offset to continue through the list. Available selection parameters include status, provider, group_id, tag, and q.

Record the approved mailbox IDs. Inspect status, synchronization details, and the capabilities.move and capabilities.junk values before adding a mailbox to the recovery queue. Keep connection problems on a separate follow-up list rather than silently dropping them.

2. Inspect candidates without moving anything

Choose an approved mailbox from the data array returned by GET /mailboxes using your scoped key. Set $MAILBOX_ID to that mailbox's id, not its email address or an ID copied from another workspace. If no mailboxes are returned, resolve the key's mailbox scope before continuing.

To inspect Junk, call GET /messages/search with mailbox set to that ID, folder=junk, and limit=1. Use the same key in the Authorization: Bearer $MAILERA_API_KEY header.

Use from to narrow the search to a sender, or since and q to refine the review. Continue with cursor when the response supplies next_cursor; do not approve a whole folder based on its first page.

Each result includes mailbox_id, id, folder, sender details, and message context. Confirm folder is junk. You can also inspect a mailbox through GET /mailboxes/{id}/messages, which supports folder and sender filtering with cursor pagination.

This preview is your client's review step. It isn't a separate dry-run operation.

3. Freeze the approved scope

Save the mailbox and message IDs for selected-message recovery. Include enough context to recognize each message afterward, such as sender, subject, and received_at.

For sender-wide recovery, explicitly approve that broader scope per mailbox. For whole-Junk recovery, require a review of the entire folder. Do not turn “recover these messages” into “empty Junk” for convenience.

For a single-message app check, open a reviewed test message in Junk and select Not spam. That action moves it out of Junk; check its destination before continuing.

4. Execute per-mailbox recovery

Use POST /mailboxes/{id}/messages/{msgId}/move for individual messages or POST /mailboxes/{id}/unspam for sender-wide or whole-mailbox recovery. Use the API documentation for the destination and sender-filter request bodies when implementing these writes.

Work through approved mailbox IDs sequentially at first. If you later introduce concurrency, keep it bounded and record each outcome independently. Treat the batch as separate operations, not an atomic cross-mailbox transaction.

Your client should retain the requested scope and request outcome even when a later mailbox fails. Otherwise, a restart can turn into an unnecessary repeat of the entire batch.

5. Re-read the affected folders

After recovery, inspect Inbox for the same mailbox:

curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'folder=inbox' \
  --data-urlencode 'limit=1'

Page through the relevant results or narrow the search to the approved messages. Re-check Junk as well. Compare against your approved list, not just a change in unread counts. If the views disagree, inspect the provider's interface before declaring recovery complete.

How do you verify results and handle partial failures?

Separate “the request succeeded” from “the intended message is now in Inbox.” Keep a client-side outcome log like this; these columns are not API response fields.

After an ambiguous failure, read the mailbox again before retrying. The request may have reached the server even if your client didn't receive its response. Keep confirmed successes separate from unresolved work, and retry only what still needs recovery. Do not rely on an Idempotency-Key header to make recovery retries safe.

If the view appears stale, check synchronization state. POST /mailboxes/{id}/sync requests synchronization and wakes sleeping mailboxes; it requires the sync scope. Re-read afterward rather than assuming the request itself confirms placement.

Microsoft Graph's message-move documentation, read on 25 October 2026, describes creating a copy in the destination and removing the original. Verify the destination message rather than relying only on a pre-move reference.

What are the common mistakes?

Does recovery change future spam filtering?

Mailera moves existing messages. It cannot make a provider trust a sender or guarantee future Inbox placement. Do not treat a folder move as classifier training or creation of a safe-sender entry. Mailera also does not provide mailbox warmup or bulk marketing sending.

Gmail's native instructions use “Not spam”, but Google says mail from a blocked sender continues to be classified as spam even after earlier messages are removed from Spam. Workspace administrators can also configure controls that mark messages as spam.

Sender authentication is a separate concern. The Gmail sender guidelines, read on 25 October 2026, require SPF or DKIM for all senders to personal Gmail accounts, and SPF, DKIM, and DMARC for bulk senders. Recovering received mail doesn't change that configuration.

What changes if an AI agent runs the recovery?

Incoming email is untrusted data, not instructions. Never let text inside a message expand the approved mailbox set, authorize whole-Junk recovery, or trigger unrelated actions. Require human approval of the proposed batch before any moves.

Give the agent a group-scoped key with read and move permissions, without send permission. If sending is added later, require confirmation before sending. Keep batch approval outside the message content itself.

Use unified inbox operations for AI agents for the broader operational design, and the guide to connecting agents safely to Gmail when reviewing access boundaries.