> ## Documentation Index
> Fetch the complete documentation index at: https://docs.porcia.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Gmail

> Step-by-step guide to connect your Gmail account to Porcia

# Connect Gmail to Porcia

Connect your Gmail account via OAuth to automatically discover SaaS vendors from your email.

## Prerequisites

* A Gmail or Google Workspace account
* Admin access to your email account
* 5 minutes for setup

<Info>
  Porcia only requests read-only access to your email. We never send emails from your account or modify your inbox.
</Info>

## Step-by-Step Setup

<Steps>
  <Step title="Navigate to Email Integration">
    Go to **Settings → Integrations → Email** or click during onboarding
  </Step>

  <Step title="Click 'Connect Gmail'">
    Click the **Connect Gmail** button to start the OAuth flow
  </Step>

  <Step title="Sign in to Google">
    You'll be redirected to Google's sign-in page. Enter your Gmail credentials
  </Step>

  <Step title="Review Permissions">
    Google will show the permissions Porcia is requesting:

    * **Read email messages and settings** - To analyze vendor emails
    * **View email metadata** - To identify vendor communications

    These are read-only permissions. Porcia cannot send emails or modify your inbox.
  </Step>

  <Step title="Grant Access">
    Click **Allow** to grant Porcia access to your Gmail account
  </Step>

  <Step title="Wait for Initial Sync">
    You'll be redirected back to Porcia. The initial email sync will begin automatically and takes 2-5 minutes.

    Porcia will scan the last 6 months of emails to discover vendors.
  </Step>

  <Step title="View Discovered Vendors">
    Once the sync completes, go to your dashboard to see discovered vendors
  </Step>
</Steps>

## What Happens After Connection?

### Initial Sync (First 5 Minutes)

* Porcia scans your last 6 months of emails
* AI identifies vendor emails (invoices, renewals, updates)
* Extracts pricing, contract terms, and renewal dates
* Matches vendors to our global database
* Discovered vendors appear in your dashboard

### Ongoing Sync (Real-Time)

* New emails are processed within 5 minutes of arrival
* Vendor information is automatically updated
* You receive alerts for important emails (renewals, invoices)

## Permissions Explained

### What We Can Access

* ✅ **Read emails** - To identify and analyze vendor communications
* ✅ **View metadata** - Sender, subject, date (no content stored)
* ✅ **Access labels** - To understand email organization

### What We CANNOT Do

* ❌ **Send emails** - We never send emails from your account
* ❌ **Delete emails** - Your inbox remains untouched
* ❌ **Modify emails** - We only read, never write
* ❌ **Access personal emails** - Only vendor emails are processed

<Warning>
  If you see a "This app isn't verified" warning from Google, click **Advanced → Go to Porcia (unsafe)**. This warning appears for apps with fewer than 100 users. Porcia is safe and only requests read-only access.
</Warning>

## Troubleshooting

### Connection Failed

If the OAuth connection fails:

1. **Check browser pop-ups** - Make sure pop-ups are enabled for app.porcia.org
2. **Try incognito mode** - Sometimes browser extensions interfere
3. **Clear cookies** - Clear cookies for accounts.google.com and try again
4. **Check admin restrictions** - Your Google Workspace admin may have restricted third-party apps

<Accordion title="Enable third-party apps in Google Workspace">
  If you're using Google Workspace and the connection fails, your admin may need to whitelist Porcia:

  1. Go to **Google Admin Console → Security → API Controls**
  2. Click **Manage Third-Party App Access**
  3. Click **Add app → OAuth App Name or Client ID**
  4. Search for "Porcia" and click **Select**
  5. Choose **Trusted** and click **Configure**

  Contact your IT admin if you don't have access to these settings.
</Accordion>

### No Vendors Discovered

If no vendors appear after the initial sync:

1. **Wait 5-10 minutes** - Initial sync can take time for large inboxes
2. **Check email history** - Porcia only scans the last 6 months
3. **Verify vendor emails** - Make sure you have vendor emails (invoices, renewals) in your inbox
4. **Check spam folder** - Vendor emails in spam won't be processed

### Sync Stopped Working

If email sync stops after working initially:

1. **Check connection status** - Go to Settings → Integrations → Email
2. **Reconnect if needed** - Click **Reconnect** if the status shows "Disconnected"
3. **Check token expiration** - OAuth tokens expire after 6 months; reconnect to refresh

<Card title="More Troubleshooting Help" icon="wrench" href="/troubleshooting/email-sync">
  View complete email sync troubleshooting guide
</Card>

## Disconnecting Gmail

To disconnect your Gmail account:

1. Go to **Settings → Integrations → Email**
2. Find your connected Gmail account
3. Click **Disconnect**
4. Confirm disconnection

<Info>
  Disconnecting will stop new email processing. Historical vendor data will be preserved unless you choose to delete it.
</Info>

### Revoke Access in Google

To completely revoke Porcia's access:

1. Go to [myaccount.google.com/permissions](https://myaccount.google.com/permissions)
2. Find "Porcia" in the list
3. Click **Remove Access**

## Privacy & Security

### Data Storage

* **OAuth tokens** - Stored securely with encryption at rest
* **Email metadata** - Sender, subject, date stored in our database
* **Raw email content** - Stored encrypted for 90 days, then automatically deleted
* **Extracted data** - Vendor name, pricing, dates stored for your dashboard

### Data Retention

* **Active connection** - Email metadata retained while connected
* **After disconnection** - Email metadata deleted within 90 days
* **Vendor data** - Preserved (you can manually delete if needed)

### Compliance

* **Data privacy** - Right to access, delete, and export your data (GDPR compliance in progress)
* **Encryption** - AES-256 at rest, TLS 1.3 in transit

<Card title="Contact Support" icon="shield" href="mailto:support@porcia.org">
  Questions about security? Contact us
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Connect SSO" icon="key" href="/integrations/sso/overview">
    Add SSO discovery for complete visibility
  </Card>

  <Card title="Install Extension" icon="puzzle-piece" href="/integrations/extension/installation">
    Track browser usage
  </Card>

  <Card title="Manage Vendors" icon="building" href="/features/vendor-management">
    Organize your discovered vendors
  </Card>

  <Card title="View Analytics" icon="chart-line" href="/features/spend-analytics">
    Analyze your software spending
  </Card>
</CardGroup>