Connect and troubleshoot integrations

Connect Gmail and Xero, verify inbound email routing, and interpret common integration status messages safely.

Use this guide when a workspace admin needs to connect Gmail or Xero, confirm inbound email routing, or decide what a status message means before escalating to support.

This page is safe to share with workspace admins. It does not include webhook URLs, signing secrets, OAuth client secrets, cron tokens, or raw email payload examples.

#Start from Settings

Open Settings and choose Integrations. Only workspace owners and admins can connect or disconnect Gmail and Xero. Dispatchers can work in the inbox, but they cannot change integration credentials.

The integration screen is the source of truth for setup checks:

Gmail Integration shows the monitored mailbox, health badge, last processed time, success rate, recent runs, and any last error.
Xero Integration shows the connected Xero organization, integration status, pending/synced/failed sync counts, recent sync jobs, and any last error.
If the workspace is locked, archived, read-only, or otherwise not writable, connect and disconnect actions are disabled until the workspace status is corrected.

Use the related workflow guides after setup is healthy:

#Connect Gmail

Connect Gmail when the workspace needs emails to land in the ATOM inbox, or when quotes and replies must be sent from the connected Gmail account.

Open Settings → Integrations.
In Gmail Integration, choose Connect Gmail or Reconnect.
Review the consent screen. ATOM uses Gmail access to read and label mailbox messages and to send replies or Gmail-backed quote emails from the connected mailbox.
Finish the Google consent flow and return to ATOM.
Confirm the success banner says Gmail connected or reconnected.
Confirm Inbox monitored shows the mailbox address you expected.

Gmail is connected at the workspace level. Do not connect a personal mailbox unless that mailbox is the approved workspace operations inbox. Everyone who can use the workspace inbox will work from the same monitored mailbox context.

#Verify Gmail processing

After connecting Gmail, verify the setup before relying on it for operations.

Open Settings → Integrations and confirm the Gmail badge is healthy.
Confirm Inbox monitored is the correct workspace mailbox.
Confirm Last processed changes after new mail arrives or after the next processing run.
Open Inbox and check that the expected thread appears.
For a linked work order, use Open in Inbox to confirm the same thread opens before replying or sending a Gmail-backed quote.

If a newly connected mailbox does not process immediately, wait for the next background run and then refresh Settings and Inbox. If the health badge changes to unhealthy, use the visible last error and latest run details for escalation.

#Disconnect or reconnect Gmail

Use Reconnect when the mailbox is still the right operations inbox but consent, refresh access, or mailbox permissions need to be refreshed.

Use Disconnect only when ATOM should stop processing the workspace mailbox. Disconnecting stops new email processing immediately and removes stored Gmail credentials from ATOM. Existing work orders, inbox records, comments, quotes, invoices, and audit history remain available according to normal retention rules.

After disconnecting, confirm:

Gmail Integration returns to the connect state.
No new Gmail threads appear from that mailbox.
Operators know to use another approved communication path until Gmail is reconnected.

#Gmail status messages

Use these meanings when the UI shows a Gmail warning.

Only admins can connect Gmail means the signed-in user is not an owner or admin. Ask a workspace admin to connect it.
Gmail connection was cancelled means the Google consent flow was closed or denied. Start Connect Gmail again.
Gmail did not grant offline access means Google did not return long-term access. Revoke the app in the Google account settings, then reconnect from ATOM.
Gmail not configured means the server-side OAuth configuration is missing. Escalate to support with the workspace and timestamp.
Workspace changes are temporarily unavailable means the workspace is locked, read-only, archived, or otherwise not writable. Resolve the workspace status first.
Could not create the required processing label means ATOM could not create or find its processing label in Gmail. Confirm the mailbox owner granted the requested Gmail permissions, then reconnect.
unhealthy with a last error means recent processing failed repeatedly. Do not keep retrying blindly; collect the last error, latest run time, mailbox address, and affected thread.
disabled means Gmail is disconnected or intentionally stopped for this workspace.

#Connect Xero

Connect Xero when quotes and invoices should sync to the workspace accounting organization.

Open Settings → Integrations.
In Xero Integration, choose Connect Xero or Reconnect Xero.
Sign in to Xero and approve access for the correct organization.
Return to ATOM and confirm the integration card shows connected.
Confirm Organization shows the Xero organization you intended to use.

ATOM stores one Xero organization connection for the workspace. Agencies and billing contacts are mapped inside that workspace. If the Xero organization name is wrong, reconnect with the correct Xero account before sending quotes or syncing invoices.

#Verify Xero sync

Use the Xero card and the quote or invoice record together.

In Settings → Integrations, confirm the Xero status is connected.
Confirm recent sync jobs are either empty for a new workspace or moving from pending to succeeded after quote or invoice work.
On quote records, use Queued in Xero, Xero send failed, and timeline entries to understand quote email delivery.
On invoice records, use Xero Pending, Xero Error, and Xero Synced as sync state, not as the full payment history.
When an invoice is synced to Xero, treat Xero as the source of truth for payment changes.

If a sync stays pending for more than one normal processing window, or if failed jobs repeat with the same error, collect the workspace, organization name, quote or invoice number, visible sync status, and latest job error before escalating.

#Xero status messages

Use these meanings when the UI shows a Xero warning.

connected means ATOM has an active Xero connection for the workspace.
error means ATOM could not use the stored Xero connection. Reconnect Xero unless support asks you to wait.
revoked means access was removed in Xero or is no longer usable. Reconnect from Settings.
pending means a sync job is waiting or running.
processing means the background worker has claimed the job.
succeeded means the job completed.
failed means the job failed after processing. Read the last error and decide whether it is a data issue, contact mapping issue, or provider issue.
Xero Pending on an invoice means ATOM has a local invoice and a Xero sync job is pending or running.
Xero Error means the invoice did not sync. Fix the integration or data problem before relying on Xero for that invoice.
Xero Synced means the Xero record exists and Xero should be treated as the accounting source of truth.
Queued in Xero on a quote means Xero email delivery is still pending or processing.
Xero send failed means Xero delivery failed. Resolve the recipient, integration, or Xero quote issue before creating a replacement send path.

#Verify inbound email routing

Some workspaces receive inbound messages through a managed inbound email address instead of a directly connected Gmail mailbox. Operators should verify the public behavior without asking for internal webhook or signing details.

Confirm the workspace has an approved inbound email address from onboarding or support.
Send a small test email from an approved sender to that address.
Open Inbox and confirm the thread appears under the expected workspace and agency context.
If the email needs review, check whether the inbox item says it needs an address, tenant contact, agency match, or another missing detail.
If the email does not appear, collect the sender, recipient address, subject, approximate send time, and workspace name for support.

Common inbound outcomes are:

created means ATOM created a new work order from the email.
linked means ATOM linked the email to existing context.
pending_review means an operator must confirm missing or low-confidence details.
unknown_sender means ATOM could not match the sender or route to an agency confidently.
duplicate means ATOM already accepted that provider message.
skipped means the route, workspace, or provider configuration is not active for that message.
failed means ATOM accepted enough context to record a failure and support should investigate.

#Message bodies and replies

Inbox rows may load quickly with a snippet first. Full text or HTML message bodies hydrate only when the thread view requests them. If a body is missing, refresh the thread once and then escalate with the thread URL and message timestamp.

Replies have stricter rules:

Replies require an authenticated owner, admin, or dispatcher.
The workspace must be writable.
The selected message must belong to the active workspace.
The reply must have at least one To address and a non-empty body.
Gmail-backed replies require a healthy Gmail integration for the original thread.
ATOM rate-limits repeated sends from the same user to prevent accidental loops.

If ATOM says Gmail accepted the reply but the inbox timeline has not finished recording it, do not send the same reply again. Wait for support to reconcile the existing idempotency record.

#Escalate safely

Escalate when a workspace admin cannot resolve the setup from the screens above, when a status stays failed after reconnecting, or when a sent quote, invoice, or reply may have reached a customer but ATOM did not finish recording it.

Include only safe operational context:

workspace name and tenant URL
integration area: Gmail, Xero, inbound email, message body, or reply
visible status badge, banner, or last error
affected mailbox address or inbound address, if it is already visible to the customer
affected quote, invoice, work order, or inbox thread URL
approximate timestamp and timezone

Do not include secrets, raw tokens, full raw email source, private attachments, or screenshots that expose unrelated customer data.

#Setup checklist

Use this checklist before marking an integration setup complete.

Gmail shows the expected monitored mailbox and a healthy status, or the workspace intentionally uses managed inbound routing instead.
Xero shows the expected organization and a connected status when accounting sync is in scope.
A test inbound email reaches the inbox or produces a documented pending-review state.
A test Gmail-backed reply or quote send is only attempted from the correct thread and workspace.
Xero quote and invoice states are interpreted using the quote and invoice guides, not from the integration card alone.
Support has enough safe context to investigate any remaining failure without receiving secrets.