Sign in

Authorize or re-authorize a connected mailbox

An Admin restores a mailbox connection whose OAuth grant was revoked or whose IMAP/SMTP credentials stopped working, without losing its history, rules or signature.

When this happens: Admin clicks Reconnect on a degraded mailbox, or follows a notification link.

Step by step

  1. 1

    Open /admin/channels/email/{id} and sees Requires re-authorization.

    A refresh failure moves the connection to RequiresReauth after the failure threshold (3 consecutive failures), or immediately on an authentication error. EasyCRM notifies Admins of the channel connection problem (FR-10).

  2. 2

    Click Reconnect.

    EasyCRM re-runs the OAuth consent screen (Gmail/Outlook) or re-prompts for host/credentials (IMAP/SMTP).

  3. 3

    Completes consent, or re-enters credentials.

    EasyCRM verifies the address is unchanged, updates the encrypted credentials, sets Active, resets ConsecutiveFailures, and resumes MailboxSyncJob from the last checkpoint. EasyCRM records audit entry ChannelConnectionReauthorized.

Other paths

Proactive re-authorization

Reconnects an Active IMAP/SMTP mailbox to rotate its app password, following steps 4–8 without a prior failure.

If something goes wrong

Address mismatch

At step 7 the reconnection completes for a different mailbox address. Rejects with EasyCrm:Channel:AddressMismatch; the Admin must connect the new address separately.

Re-authorization still fails

Credentials are rejected again. The connection stays RequiresReauth; the error is shown inline.

Good to know

  • No history, rules or signature is lost on re-authorization.
  • The mailbox address cannot change through re-authorization.