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.

Use the integration screen 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 a few minutes 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 ATOM cannot start Gmail authorization for this environment. 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, update payment status in Xero first.

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 Xero sync is waiting or running.
processing means ATOM is sending or updating the record now.
succeeded means Xero accepted the update.
failed means the sync failed. Read the last error and fix the shown data, contact, integration, or Xero issue before retrying.
Xero Pending on an invoice means ATOM is still syncing the invoice to Xero.
Xero Error means the invoice did not sync. Fix the shown problem before relying on Xero for that invoice.
Xero Synced means the Xero invoice exists. Update payment status in Xero first.
Queued in Xero on a quote means Xero email delivery is still waiting or sending.
Xero send failed means Xero delivery failed. Resolve the recipient, integration, or Xero quote issue before choosing another 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: ATOM created a new work order from the email.
linked: ATOM attached the email to an existing record.
pending_review: review the thread and confirm missing or low-confidence details.
unknown_sender: link the sender to the right agency before creating work.
duplicate: ATOM has already accepted that message.
skipped: the message did not match an active inbound email setup for this workspace.
failed: support should investigate with the sender, recipient, subject, timestamp, and workspace name.

#Message bodies and replies

Inbox rows may show a snippet before the full message body appears. If the body is still missing after you refresh the thread once, escalate with the thread URL and message timestamp.

Replies have stricter rules:

You must be an owner, admin, or dispatcher.
The workspace must allow changes.
The selected message must belong to the workspace you are using.
The reply must have at least one To address and a non-empty body.
Gmail-backed replies require a healthy Gmail connection 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 updated yet, do not send the same reply again. Escalate with the thread URL and send time.

#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 shows a pending-review state.
A test Gmail-backed reply or quote send is attempted only 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.