> ## 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.

# Email Sync Troubleshooting

> Fix common email integration and sync issues

# Email Sync Troubleshooting

Having trouble with email integration or sync? This guide covers the most common issues and their solutions.

## Common Issues

<AccordionGroup>
  <Accordion title="No vendors discovered after connecting email">
    **Possible causes:**

    * Initial sync still in progress
    * No vendor emails in the scanned period
    * Email integration not properly connected
    * Vendor emails in spam/junk folder

    **Solutions:**

    1. **Wait 5-10 minutes** - Initial sync can take time for large inboxes
    2. **Check email history** - Porcia scans last 6 months; ensure you have vendor emails in this period
    3. **Verify connection** - Go to Settings → Integrations → Email and check status
    4. **Check spam folder** - Vendor emails in spam won't be processed
    5. **Manual test** - Forward a vendor email to your Porcia address to test processing
  </Accordion>

  <Accordion title="Email sync stopped working">
    **Possible causes:**

    * OAuth token expired
    * Email provider revoked permissions
    * Account password changed
    * Email provider API issues

    **Solutions:**

    1. **Reconnect integration** - Go to Settings → Integrations → Email → Reconnect
    2. **Check permissions** - Verify Porcia still has access in your email provider
    3. **Re-authenticate** - Complete OAuth flow again
    4. **Check account status** - Ensure your email account is active and accessible
    5. **Contact support** - If issue persists after reconnection
  </Accordion>

  <Accordion title="Gmail connection failed">
    **Possible causes:**

    * Browser blocking pop-ups
    * Google Workspace admin restrictions
    * Incorrect Google account
    * "This app isn't verified" warning

    **Solutions:**

    1. **Enable pop-ups** - Allow pop-ups for app.porcia.org
    2. **Try incognito mode** - Disable browser extensions that might interfere
    3. **Use correct account** - Sign in with the Google account you want to connect
    4. **Handle verification warning** - Click "Advanced → Go to Porcia (unsafe)"
    5. **Check admin settings** - Ask IT admin to whitelist Porcia in Google Workspace
  </Accordion>

  <Accordion title="Outlook connection failed">
    **Possible causes:**

    * Microsoft 365 admin restrictions
    * Incorrect Microsoft account
    * Browser compatibility issues
    * Two-factor authentication issues

    **Solutions:**

    1. **Use correct account** - Sign in with your Outlook/Microsoft 365 account
    2. **Check admin restrictions** - Verify third-party apps are allowed
    3. **Try different browser** - Use Chrome or Edge for best compatibility
    4. **Complete 2FA** - Ensure two-factor authentication is completed
    5. **Clear cookies** - Clear cookies for login.microsoftonline.com
  </Accordion>

  <Accordion title="Email forwarding not working">
    **Possible causes:**

    * Forwarding rules not set up correctly
    * Wrong Porcia forwarding address
    * Email provider blocking forwarding
    * Forwarding rules disabled

    **Solutions:**

    1. **Verify forwarding address** - Check your unique address in Settings → Integrations → Email
    2. **Test forwarding rules** - Send a test email to verify rules are working
    3. **Check rule status** - Ensure forwarding rules are active in your email provider
    4. **Manual forward test** - Manually forward a vendor email to test processing
    5. **Review rule criteria** - Ensure forwarding rules match vendor emails
  </Accordion>
</AccordionGroup>

## Gmail-Specific Issues

### OAuth Connection Problems

**Error: "This app isn't verified"**

```
Solution:
1. Click "Advanced" in the warning dialog
2. Click "Go to Porcia (unsafe)"
3. This is a standard Google warning for newer apps
4. Porcia is safe and only requests read-only access
```

**Error: "Access blocked"**

```
Solution:
1. Check if your Google Workspace admin has restricted third-party apps
2. Ask admin to whitelist Porcia in Admin Console
3. Go to Admin Console → Security → API Controls → Manage Third-Party App Access
4. Add Porcia as a trusted application
```

**Error: "Invalid scope"**

```
Solution:
1. Clear browser cookies for accounts.google.com
2. Sign out of all Google accounts
3. Try the connection process again
4. Use incognito mode if the issue persists
```

### Gmail Sync Issues

**Emails not being processed:**

1. Check if emails are from known vendor domains
2. Verify emails aren't in spam folder
3. Ensure emails contain vendor-related content (invoices, renewals)
4. Check if Gmail labels are interfering with processing

**Partial email discovery:**

1. Gmail API rate limits may cause delays
2. Large inboxes take longer to process
3. Wait 24 hours for complete sync
4. Check sync status in Settings → Integrations → Email

### Gmail Admin Configuration

<Accordion title="Whitelist Porcia in Google Workspace">
  **For Google Workspace administrators:**

  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. Select **Trusted** and click **Configure**
  6. Choose organizational units that can access Porcia
  7. Click **Finish**

  **Alternative method:**

  1. Go to **Security → Less secure app access**
  2. Enable **Allow users to manage their access to less secure apps**
  3. Users can then grant access to Porcia
</Accordion>

## Outlook-Specific Issues

### OAuth Connection Problems

**Error: "AADSTS50020: User account does not exist"**

```
Solution:
1. Ensure you're signing in to the correct tenant
2. Use your work/school account, not personal Microsoft account
3. Check the tenant ID in the URL
4. Contact your IT admin if you're unsure about the correct account
```

**Error: "Admin consent required"**

```
Solution:
1. Your organization requires admin approval for new apps
2. Contact your Microsoft 365 administrator
3. Admin needs to pre-approve Porcia in Azure AD
4. Alternatively, admin can grant consent during your connection attempt
```

**Error: "Conditional access policy blocked"**

```
Solution:
1. Your organization has conditional access policies
2. Contact your IT administrator
3. Admin may need to create an exception for Porcia
4. Or connect from a compliant device/location
```

### Outlook Sync Issues

**Microsoft Graph API limits:**

* Outlook has stricter API rate limits than Gmail
* Sync may take longer for large mailboxes
* Retry automatically after rate limit resets
* Consider connecting during off-peak hours

**Exchange Online vs Outlook.com:**

* Both are supported but have different capabilities
* Exchange Online (Microsoft 365) provides richer data
* Outlook.com has more limited API access
* Some features may not be available on Outlook.com

### Microsoft 365 Admin Configuration

<Accordion title="Pre-approve Porcia in Azure AD">
  **For Microsoft 365 administrators:**

  1. Go to **Azure Portal → Azure Active Directory → Enterprise applications**
  2. Click **New application → Create your own application**
  3. Enter "Porcia" as the application name
  4. Select **Integrate any other application you don't find in the gallery**
  5. Click **Create**
  6. Go to **Properties** and configure as needed
  7. Go to **Users and groups** to assign users
  8. Go to **Permissions** and grant admin consent for required permissions

  **Required permissions:**

  * Mail.Read (Read user mail)
  * User.Read (Sign in and read user profile)
  * offline\_access (Maintain access to data)
</Accordion>

## Email Forwarding Issues

### Forwarding Rules Not Working

**Gmail forwarding issues:**

1. **Check filter criteria** - Ensure filters match vendor emails
2. **Verify forwarding address** - Must be exact Porcia address
3. **Test with manual forward** - Forward an email manually to test
4. **Check forwarding verification** - Gmail may require verification

**Outlook forwarding issues:**

1. **Check rule conditions** - Verify rule criteria are correct
2. **Rule order matters** - Ensure Porcia rule has correct priority
3. **Test rule** - Use Outlook's rule testing feature
4. **Check rule status** - Ensure rule is enabled and active

### Common Forwarding Mistakes

**Wrong forwarding address:**

```
❌ Wrong: support@porcia.org
❌ Wrong: workspace@porcia.org
✅ Correct: username.workspace-slug@inbox.porcia.org
```

Each user has their own unique forwarding address — find yours in Settings → Email Forwarding.

**Incorrect filter criteria:**

```
❌ Too broad: Subject contains "email"
❌ Too narrow: From exactly "billing@salesforce.com"
✅ Good: From contains "@salesforce.com"
✅ Good: Subject contains "invoice" OR "renewal"
```

**Missing rule activation:**

* Rules created but not activated
* Rules disabled due to errors
* Rules overridden by other rules
* Rules not applied to existing emails

## Sync Status Monitoring

### Check Sync Status

1. Go to **Settings → Integrations → Email**
2. View connection status for each integration
3. Check last sync time and status
4. Look for error messages or warnings

### Sync Status Indicators

**Connected ✅**

* Integration is working properly
* Recent sync completed successfully
* New emails being processed

**Syncing 🔄**

* Sync currently in progress
* Normal for initial setup or large inboxes
* Wait for completion

**Error ❌**

* Sync failed due to an issue
* Click for error details
* May need to reconnect

**Disconnected ⚠️**

* Integration was disconnected
* OAuth token may have expired
* Need to reconnect

### Manual Sync

Force a manual sync if needed:

1. Go to **Settings → Integrations → Email**
2. Click **Sync Now** next to your integration
3. Wait for sync to complete
4. Check for any error messages

<Warning>
  Manual sync should only be used occasionally. Frequent manual syncs may hit API rate limits.
</Warning>

## Performance Optimization

### Large Mailbox Optimization

**For mailboxes with 100,000+ emails:**

1. Initial sync may take 2-4 hours
2. Consider connecting during off-peak hours
3. Ensure stable internet connection
4. Don't interrupt the initial sync process

**Reduce sync load:**

1. Archive old emails before connecting
2. Clean up spam folder
3. Organize emails with labels/folders
4. Consider using email forwarding for new emails only

### API Rate Limits

**Gmail rate limits:**

* 1 billion quota units per day
* 250 quota units per user per 100 seconds
* Porcia automatically handles rate limiting

**Outlook rate limits:**

* 10,000 requests per 10 minutes per app per mailbox
* Porcia implements exponential backoff
* Sync may slow down during peak usage

## Data Quality Issues

### Vendor Not Recognized

**If a vendor isn't automatically recognized:**

1. Check if email is from a known vendor domain
2. Manually add vendor in Porcia dashboard
3. Update vendor aliases for future recognition
4. Report unknown vendors to support for database updates

### Incorrect Data Extraction

**If pricing or dates are extracted incorrectly:**

1. Manually correct the information in vendor profile
2. Upload the original invoice/contract for reference
3. Report extraction errors to support for AI improvement
4. Consider using structured email templates with vendors

### Duplicate Vendors

**If the same vendor appears multiple times:**

1. Use vendor merge feature in dashboard
2. Check for different email domains from same vendor
3. Update vendor aliases to prevent future duplicates
4. Consolidate historical data during merge

## Getting Help

### Self-Service Options

1. **Check sync status** - Settings → Integrations → Email
2. **Review error messages** - Click on error indicators for details
3. **Try reconnection** - Disconnect and reconnect integration
4. **Manual sync** - Force a sync to test connectivity

### Contact Support

**When to contact support:**

* Error persists after reconnection
* Sync has been stuck for over 24 hours
* Data extraction is consistently incorrect
* Integration worked before but suddenly stopped

**Information to include:**

* Email provider (Gmail, Outlook, etc.)
* Error messages or screenshots
* When the issue started
* Steps you've already tried
* Your Porcia workspace ID

<CardGroup cols={2}>
  <Card title="Contact Support" icon="life-ring" href="mailto:support@porcia.org">
    Email: [support@porcia.org](mailto:support@porcia.org)
  </Card>

  <Card title="Live Chat" icon="message-circle">
    Use the chat widget in bottom-right corner
  </Card>
</CardGroup>

## Prevention Tips

### Best Practices

1. **Regular monitoring** - Check sync status weekly
2. **Keep credentials updated** - Update passwords in Porcia when changed
3. **Monitor vendor emails** - Ensure important emails aren't going to spam
4. **Backup important data** - Export vendor data periodically
5. **Stay informed** - Subscribe to Porcia status updates

### Maintenance Schedule

**Monthly:**

* Review sync status for all integrations
* Check for new vendor discoveries
* Verify data accuracy for key vendors

**Quarterly:**

* Audit email forwarding rules
* Review and update vendor aliases
* Clean up duplicate or incorrect vendor entries

**Annually:**

* Review and renew OAuth connections
* Audit email integration permissions
* Update forwarding rules for new vendor domains