Skip to content
AptiroAptirodocs
Menu: Connect your Gmail

Integrations

Connect your Gmail

On this page

Connecting Gmail lets Aptiro log the email you already send and receive against the right contact, without you copying anything in. The connection is your own: you connect your own mailbox from Preferences > Email, and no colleague, admin or owner can connect it for you or read it through their own session.

Gmail sync is on the Growth plan and above. On Starter, Preferences > Email names the plan instead of a Connect button. If your workspace moves off Growth after connecting, the connection is paused rather than disconnected: your grant, your stored history position and everything already logged are all kept, and getting the plan back resumes it on its own, with nothing to reconnect.

What Aptiro reads, and what it does not

This is worth reading before you connect, because an email that is logged becomes visible to other people.

Aptiro reads your Gmail only to find email with people who are already contacts in your organisation's Aptiro. Those messages become activities on that contact's account, carrying the subject, the time, the direction and an excerpt of the message.

  • Connecting reads the last 90 days as well as new mail. The first sync goes back three months, so the contacts you already deal with have their recent history straight away rather than starting empty. After that it stays live. The same rule applies throughout: only email with people who are already contacts, in that window or any other.
  • An email activity is an ordinary activity. Anyone who can see that account can read it, the same as a logged call or meeting note.
  • Email that matches no contact is ignored entirely. Nothing about it is stored: not the subject, not the sender, not the fact that it existed. Your personal mail, your payslips and your doctor's appointments stay out of a shared system because they never match anyone.
  • Aptiro never sends, replies to, deletes, labels or changes anything in your mailbox. The access it asks Google for is read-only (gmail.readonly), which cannot write.
  • Attachments are not downloaded or stored.
  • Free email providers (gmail.com, outlook.com, and similar) are excluded by default. A contact on one of those addresses is not logged unless an admin turns that default off for your organisation. See Exclude domains and addresses below.

Before you start

An admin or owner has to set up your organisation's own Google credentials first, in Settings > Integrations, using the same client id and secret the Google Calendar connection uses. If nobody has, the Connect button will tell you to ask them.

Because every organisation brings its own Google Cloud project, the Gmail API has to be enabled on it and gmail.readonly added to its OAuth consent screen. Google treats that scope as restricted, so a project used outside your own Google Workspace may need verifying with Google. An internal Workspace app does not.

Connect

  1. Go to Preferences > Email.
  2. Read the notice at the top of the panel, then select Connect Gmail.
  3. Sign in to the Google account whose mail you want logged, and approve the access Google describes.
  4. You come back to Preferences, where the panel shows Connected and the address you granted.

If you approve with the wrong account, disconnect and connect again with the right one.

What happens after you connect

The first pass works through the last 90 days. A busy mailbox takes a few rounds rather than one long one, so the panel says Working through the last 90 days while it goes, and emails appear on their accounts as it finds them. It carries on in the background whether or not you stay on the page. Once it is done the panel says Up to date, and new email is picked up automatically every fifteen minutes.

Check for new email on the panel starts a check straight away, for when you have just sent something and want to see it logged. The check itself runs in the background: the button comes back at once saying it has started, not when it has finished, so you can close the page or carry on working and the check runs to the end regardless. You can start one at most once a minute, and not at all while one is already running.

What a check found appears under Sync history below, and on the contact's account timeline.

A logged email appears on the contact's account timeline as an ordinary activity of type Email, with the subject prefixed Sent or Received, the time it was sent, and a short excerpt of the message. The excerpt is capped at 500 characters: enough to see what was asked or agreed without opening Gmail, and deliberately not a copy of your mailbox.

A few details that are easier to know than to discover:

  • An email to people at two different accounts is logged on both. That is usually what you want, and there is no sensible way to pick one.
  • An email to two contacts at the same account is logged once, against the account rather than either person.
  • An address that is a contact at four or more accounts is ignored. An address spread that widely is a shared one (info@, a mailing list) rather than a person, and logging it everywhere would be noise for everybody.
  • Re-syncing never logs the same email twice, and neither does a colleague syncing the same thread from their own mailbox.
  • Deleting a logged activity is final. It will not come back on the next sync.
  • Drafts, spam and binned messages are not logged.
  • A contact's reply ends any sequence that was chasing them, the moment it is logged, the same as marking they replied by hand on the Today list. Mail you send never does this, only mail a contact sends you.

Exclude domains and addresses

Two places let you stop specific mail from ever being matched or logged, on top of the free-domain default above. Excluding something only changes what happens from now on: it never deletes or hides anything already logged. If a past match was wrong, remove that one email from Synced email instead.

There are two lists, held by different people:

  • Excluded domains apply to the whole organisation, and are set by an admin under Settings > Email exclusions. Use this for your own company's domain, so colleagues emailing each other is never logged as an activity. The same page has the switch for free email providers by default: turn it off if your organisation genuinely sells to people on gmail.com and similar addresses. A member who cannot manage integrations does not see that Settings page.
  • My excluded addresses, under Preferences > Email > Exclusions, are yours alone. Use this for a personal contact, such as a partner or a friend, who happens to be a contact in your organisation's Aptiro. Nobody else's sync is affected, and nobody else can see which addresses you have excluded. Members who can manage the organisation list also see a link from that tab to Settings > Email exclusions.

An address that matches both an excluded domain and your own contacts list is never logged, whichever mailbox reads it: excluding happens before Aptiro looks up whether the address is a contact at all.

See what has been logged, and remove a wrong match

Preferences > Email > Synced email lists every email your own mailbox has had logged, newest first: the subject, the account and contact it was matched to, when you sent or received it, and which of the two it was. Each row links to the account, where the activity sits on the timeline.

The list is yours alone. It shows what your mailbox caused, not your organisation's and not a colleague's, and nobody can see yours through their own Preferences.

It lists what was logged, not what was read. Email with anyone who is not already a contact is ignored and nothing about it is stored, so it is not listed here and neither is a count of it. There is nothing to count.

Remove an email that should not have been logged

Matching is by email address, so it is occasionally wrong: a shared inbox, a thread forwarded on to someone else, or a contact who has moved to another company and whose old address is still on file. The result is one of your emails on an account every colleague who can see that account can read.

Select the bin icon on the row and confirm. That:

  • deletes the activity from the account, for everyone;
  • and stops that email being logged again, on this or any later sync.

You can always remove an email your own mailbox caused, even on an account where you cannot otherwise delete activities. You are the only person who can tell that the match is wrong, so the permission to undo it sits with you rather than with the account's owner.

It cannot be undone from here. The removed row stays in the list marked Removed, so you can see the removal took and that the email is not coming back, and it keeps nothing about the email itself: no subject, no address and no time. If you want that email logged again later, log the activity by hand from the account.

An activity someone deletes from the account timeline shows here as Removed in exactly the same way, and will not be logged again either.

The tab also shows whether syncing is running, so an empty list is readable: it tells you whether nothing has matched or whether the connection has stopped and needs reconnecting.

See when your mailbox was last checked

Preferences > Email > Sync history shows Last checked at the top, which is when a check last ran whether or not it found anything, and below it a list of the checks that did find something:

  • When it ran, and how long it took.
  • Started by: You, if you pressed Check for new email, or Schedule, for the automatic check that runs every fifteen minutes.
  • Looked at: how many messages the check read the headers of.
  • Logged: how many became activities.
  • Outcome: Finished, Running, More to do (it stopped on its limit for one run and the next one carries on from there), or Did not finish, with the reason underneath.

Not every check is listed. An automatic check runs every fifteen minutes, which is 96 a day, and on most mailboxes nearly all of them find nothing. One that looked at no messages and logged none is not kept, because a page of those would bury the checks that mean something. A check you started yourself is always listed, whatever it found, and so is any check that looked at messages even if none of them were logged. Use Last checked at the top to see the automatic checks are still running.

Looked at is not kept. Most of what a check reads matches nobody in your contacts and is dropped without anything being stored, so a check that looked at 500 messages and logged 2 is the ordinary, healthy case rather than a sign something is wrong. The history itself holds only these numbers: there is no address, subject or message in it, for the same reason there is none anywhere else.

A check that says Did not finish needs nothing from you unless the panel also asks you to reconnect. The next check picks up where it stopped.

Listed checks are kept for 30 days. Older entries are removed; the email they logged is unaffected, because that lives on the account.

If Google stops honouring the connection, because you revoked Aptiro's access, changed your password, or an admin removed the app, the panel says so and offers Reconnect. Nothing is logged in the meantime, and activities already logged are unaffected. Reconnecting picks up from where it left off rather than starting the 90 days again.

Meetings with your contacts

If you have connected Google Calendar in Preferences, a meeting on your calendar appears on an account when at least one attendee's email address exactly matches a contact on that account. It is added to the account's upcoming calendar events, and the next scheduled sync picks it up, or Sync now in Preferences does.

  • Aptiro reads meetings from the last 30 days and the year ahead, and stores one only when an attendee matches a contact.
  • Only the title, the times, every attendee's address and the link to the event are kept on a matched meeting. The meeting's description is never stored, because it often holds dial-in details and private notes.
  • Meetings marked private or confidential in Google are never imported.
  • A meeting with no matching contact is never stored or recorded. Nothing about it is kept: not the title, not the attendees, and not a count of the ones skipped.
  • Your mail exclusions apply here too. An address on your excluded list, or on an excluded domain, never counts as a match, so a personal contact does not pull a meeting onto an account.
  • A meeting whose contacts sit on two different accounts is skipped, because there is no sensible way to pick one.
  • Once a meeting is on an account it stays there, and is updated if it changes, until it leaves your calendar.

Disconnect

Select Disconnect on the same panel. Aptiro revokes its access at Google and deletes the stored credential. Nothing further is read from that moment.

Activities already logged stay where they are, as a record of what happened. Disconnecting stops further reading; it does not remove what has already been logged. The Synced email tab stays available afterwards, so you can still remove any you no longer want from there, or delete them from the account or contact they sit on.

If disconnecting reports a failure, nothing has changed: your connection is left exactly as it was, so you can try again. Aptiro deliberately does not report a disconnect it could not complete.

You do not have to remember this when you leave an organisation. If an admin removes you, Aptiro revokes its access and deletes the stored credential as part of removing you.

Where the credential lives

Aptiro never stores your Google password, and never puts the refresh token Google issues into its database. It goes into a secrets store, tied to your organisation, and the database keeps only a reference to it. Disconnecting removes it. It is never sent back to a browser, whatever your role.

Last updated 2026-10-29

Search the documentation