Search email threads from your own Gmail account. An organization admin enables the source; each teammate connects their own account. An admin's connection does not make their mailbox available to the team.
Admin setup uses your organization's Settings → Integrations page. Teammates connect from Integrations in the main sidebar. For workspace Search, use Search → Add source instead; Create & Invite is the workspace equivalent of Add source.
Set up the source
These steps require a Sim organization admin.
Add Gmail
Open Settings → Integrations → Providers, approve Gmail, then select Set up. Gmail uses Member accounts; there is no domain-wide or service-account crawl in Search.
Choose what to include
Keep the defaults to search all dates and labels, excluding Promotions, Social, Spam, and Trash. Add filters below if your team needs a narrower source.
Create the source
Click Add source. Gmail appears in the Sources list. Each person, including the admin, then connects their own account.
Connect your account
- Join the Sim organization and verify your Sim email address. Open Integrations and click Connect account beside Gmail.
- Complete the connection in the tab that opens. Choose the Google account whose verified email matches your Sim email, and grant the requested permissions.
- Return to Integrations. The source shows its indexing status and the number of documents you can search.
Teammates follow these same steps after joining the organization. Once an admin approves Gmail, the first connection can create its source with default filters. Admins can configure shared filters beforehand.
Source options
An admin can change these under Manage on the Gmail source. Filters apply separately to each connected mailbox.
| Option | Behavior |
|---|---|
| Labels | Optional comma-separated names or system IDs, such as Engineering, INBOX. A thread matching any listed label is included. Leave empty for all labels. Custom IDs such as Label_7 belong to one mailbox and cannot be used for member setup. |
| Date Range | All time by default. Choose the last 7, 30, or 90 days, 6 months, or year. |
| Exclude Promotions / Exclude Social | Both enabled by default. Choose No to include either category. |
| Search Filter | Optional Gmail query, such as from:team@example.com subject:release. This filters what is indexed; it is not a Sim Search query. |
Document details contains optional metadata tags. Sync frequency and the general knowledge-base Max Threads setting are hidden in Search.
What gets indexed
Sim indexes the message text Gmail returns for each matching thread, plus subjects, senders, dates, and labels. Filters select threads; messages within a selected thread are not filtered again. HTML email is converted to text. Results link back to Gmail.
File attachments and image contents are not indexed. Thread discovery uses Gmail's default exclusion of Spam and Trash. A filter such as has:attachment selects the email thread; it does not index the attachment. Gmail API filtering also differs from Gmail's interface for aliases and thread-wide searches. See Google's thread listing reference and filtering guide.
Search schedules syncs hourly. The first sync and large mailboxes can take longer; results appear as documents are indexed. Updates and removals are reconciled during background sync, rather than fetched live for each search.
Troubleshooting
| What you see | What to do |
|---|---|
| A different email is requested | Use the Google account matching your verified Sim email. A separate personal account or alias does not satisfy the match. |
| No searchable documents | Check the source's labels, date range, category exclusions, and search filter. Allow the first sync to finish. |
| Finish connecting in the other tab | Complete the Google flow, or use Open again while authorization is pending. If the popup was blocked or closed, allow popups and select Connect account again. |
| Reconnect | Click Reconnect and authorize the same account again. |
| Unavailable or needs admin attention | Ask your Sim admin to check source status and the deployment's Google OAuth configuration. |
Self-hosted operator setup
Users do not need to create Google Cloud credentials. The deployment operator configures one Google OAuth client for the instance:
- In Google Cloud Console, select your project. Open APIs & Services → Library, find Gmail API, and enable it.
- Open Google Auth platform → Branding. Select Get started if needed, then enter the app name, support email, and contact email. Under Audience, use Internal only for an app limited to your Google Workspace organization; otherwise use External and add test users while testing. Review the app's permissions under Data Access → Add or remove scopes, using the current Sim scopes below. Follow Google's consent and verification guidance for your audience.
- Open Google Auth platform → Clients → Create client. Choose Web application, give the client a name, and add the URI below under Authorized redirect URIs. If this instance already has a Google client, add this URI to that client instead. See Google's credential setup.
- Save the client ID and secret as
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET. SetNEXT_PUBLIC_APP_URLto the same Sim origin used in the callback, then restart Sim. See Integrations & OAuth.
https://<your-sim-domain>/api/auth/oauth2/callback/google-emailThis Google Cloud example uses one client for all three services. Replace https://sim.example.com with your Sim origin and add only the callbacks for services you enable.
The current Sim Gmail connection uses these scopes:
openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.labelsGoogle's gmail.readonly scope is sufficient for Search's email reads. Sim currently shares its Gmail OAuth connection with workflow actions and requires the broader scope set above; do not substitute gmail.readonly in this setup. Search does not send or modify email. See Google's scope descriptions.