apps/docs/connectors/gmail.mdx
Connect Gmail to automatically sync email threads into your supermemory knowledge base. Supports real-time updates via Google Cloud Pub/Sub webhooks and incremental synchronization.
<Note> **Scale Plan Required:** The Gmail connector is available on Scale and Enterprise plans only. </Note>const client = new Supermemory({
apiKey: process.env.SUPERMEMORY_API_KEY!
});
const connection = await client.connections.create('gmail', {
redirectUrl: 'https://yourapp.com/auth/gmail/callback',
containerTags: ['user-123', 'gmail-sync'],
documentLimit: 5000,
metadata: {
source: 'gmail',
department: 'support'
}
});
// Redirect user to Google OAuth
window.location.href = connection.authLink;
console.log('Auth expires in:', connection.expiresIn);
```
client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))
connection = client.connections.create(
'gmail',
redirect_url='https://yourapp.com/auth/gmail/callback',
container_tags=['user-123', 'gmail-sync'],
document_limit=5000,
metadata={
'source': 'gmail',
'department': 'support'
}
)
# Redirect user to Google OAuth
print(f'Redirect to: {connection.auth_link}')
print(f'Expires in: {connection.expires_in}')
```
After user grants permissions, Google redirects to your callback URL. The connection is automatically established and the initial sync begins.
console.log('Connected email:', connection.email);
console.log('Connection created:', connection.createdAt);
// List synced email threads
const documents = await client.documents.list({
containerTags: ['user-123', 'gmail-sync']
});
console.log(`Synced ${documents.memories.length} email threads`);
```
print(f'Connected email: {connection.email}')
print(f'Connection created: {connection.created_at}')
# List synced email threads
documents = client.documents.list(
container_tags=['user-123', 'gmail-sync']
)
print(f'Synced {len(documents.memories)} email threads')
```
# List synced email threads
curl -X POST "https://api.supermemory.ai/v3/documents/list" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"containerTags": ["user-123", "gmail-sync"],
"source": "gmail"
}'
```
Gmail threads (conversations) are synced as individual documents with all messages included:
Each synced thread includes searchable metadata:
| Field | Description |
|---|---|
type | Always gmail_thread |
subject | Email subject line |
threadId | Gmail thread ID |
from | Sender email address |
to | Recipient email addresses |
date | Date of first message |
messageCount | Number of messages in thread |
attachmentCount | Number of attachments (if any) |
attachmentNames | List of attachment filenames |
You can filter searches using these metadata fields:
const results = await client.search.documents({
q: "project update",
containerTags: ['user-123'],
filters: JSON.stringify({
AND: [
{ key: "type", value: "gmail_thread", negate: false },
{ key: "from", value: "[email protected]", negate: false }
]
})
});
connections.forEach(conn => {
console.log(`Provider: ${conn.provider}`);
console.log(`ID: ${conn.id}`);
console.log(`Email: ${conn.email}`);
console.log(`Created: ${conn.createdAt}`);
console.log(`Document limit: ${conn.documentLimit}`);
console.log('---');
});
```
for conn in connections:
print(f'Provider: {conn.provider}')
print(f'ID: {conn.id}')
print(f'Email: {conn.email}')
print(f'Created: {conn.created_at}')
print(f'Document limit: {conn.document_limit}')
print('---')
```
// Delete by provider and container tags
const providerResult = await client.connections.deleteByProvider('gmail', {
containerTags: ['user-123']
});
console.log('Deleted Gmail connection:', providerResult.id);
```
# Delete by provider and container tags
provider_result = client.connections.delete_by_provider(
'gmail',
container_tags=['user-123']
)
print(f'Deleted Gmail connection: {provider_result.id}')
```
# Delete by provider and container tags
curl -X DELETE "https://api.supermemory.ai/v3/connections/gmail" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"containerTags": ["user-123"]
}'
```
Trigger a manual synchronization:
<Tabs> <Tab title="TypeScript"> ```typescript // Trigger sync for Gmail connections await client.connections.import('gmail');// Trigger sync for specific container tags
await client.connections.import('gmail', {
containerTags: ['user-123']
});
console.log('Manual sync initiated');
```
# Trigger sync for specific container tags
client.connections.import_(
'gmail',
container_tags=['user-123']
)
print('Manual sync initiated')
```
# Trigger sync for specific container tags
curl -X POST "https://api.supermemory.ai/v3/connections/gmail/import" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"containerTags": ["user-123"]
}'
```
Gmail connector supports multiple sync methods:
| Feature | Behavior |
|---|---|
| Real-time sync | Via Google Cloud Pub/Sub webhooks (7-day expiry, auto-renewed) |
| Scheduled sync | Every 4 hours |
| Manual sync | On-demand via API |
| Incremental sync | Uses Gmail historyId to fetch only changed threads |
The Gmail connector requests the following OAuth scopes:
| Scope | Purpose |
|---|---|
gmail.readonly | Read-only access to Gmail messages and threads |
userinfo.email | Access to user's email address for connection identification |
If OAuth fails or the connection stops syncing:
// Re-create connection to get fresh tokens
await client.connections.deleteByProvider('gmail', {
containerTags: ['user-123']
});
const newConnection = await client.connections.create('gmail', {
redirectUrl: 'https://yourapp.com/auth/gmail/callback',
containerTags: ['user-123']
});
// User must re-authenticate
window.location.href = newConnection.authLink;
If real-time sync isn't working:
If you see permission errors: