Gmail Database Schema

The Gmail plugin automatically syncs data from Gmail to your database. This allows you to query Gmail data without making API calls, providing faster access and offline capabilities.

New to Corsair? Learn about core concepts like database operations, data synchronization, and multi-tenancy before working with the database.

Full Implementation: For the complete, up-to-date database schema and implementations, see the Gmail plugin source code on GitHub.

Synced Entities

The Gmail plugin syncs the following entities to your database:

messages - Email messages and metadata
labels - Gmail labels
drafts - Draft messages
threads - Email conversation threads

Database API

Access synced data through the db property:

const messages = await corsair.gmail.db.messages.search({
    data: { from: "example@gmail.com" },
});

Search Options

All entity searches support the following options:

await corsair.gmail.db.messages.search({
    data: { from: "example@gmail.com" },
    limit: 100,
    offset: 0,
});

Messages

Messages are synced when you list, get, or receive message webhooks.

Schema

{
    id: string;
    threadId?: string;
    labelIds?: string[];
    snippet?: string;
    historyId?: string;
    internalDate?: string;
    sizeEstimate?: number;
    payload?: MessagePart;
    raw?: string;
    subject?: string;
    body?: string;
    from?: string;
    to?: string;
    createdAt?: Date | null;
}

Querying Messages

Search by sender:

const messages = await corsair.gmail.db.messages.search({
    data: { from: "example@gmail.com" },
});

Search by subject:

const messages = await corsair.gmail.db.messages.search({
    data: { subject: "Important" },
});

Search by label:

const inboxMessages = await corsair.gmail.db.messages.search({
    data: { labelIds: ["INBOX"] },
});

Labels

Labels are synced when you list or get labels.

Schema

{
    id: string;
    name?: string;
    messageListVisibility?: 'show' | 'hide';
    labelListVisibility?: 'labelShow' | 'labelShowIfUnread' | 'labelHide';
    type?: 'system' | 'user';
    messagesTotal?: number;
    messagesUnread?: number;
    threadsTotal?: number;
    threadsUnread?: number;
    createdAt?: Date | null;
}

Querying Labels

Search by name:

const labels = await corsair.gmail.db.labels.search({
    data: { name: "Important" },
});

Find user-created labels:

const userLabels = await corsair.gmail.db.labels.search({
    data: { type: "user" },
});

Drafts

Drafts are synced when you list, get, or create drafts.

Schema

{
    id: string;
    messageId?: string;
    createdAt?: Date | null;
}

Querying Drafts

Get all drafts:

const drafts = await corsair.gmail.db.drafts.search({
    data: {},
});

Threads

Threads are synced when you list or get threads.

Schema

{
    id: string;
    snippet?: string;
    historyId?: string;
    createdAt?: Date | null;
}

Querying Threads

Get all threads:

const threads = await corsair.gmail.db.threads.search({
    data: {},
});

Multi-Tenancy

When using multi-tenancy, all database queries are automatically scoped to the tenant:

const tenant = corsair.withTenant("tenant-id");

const messages = await tenant.gmail.db.messages.search({
    data: { from: "example@gmail.com" },
});

Each tenant's data is isolated in the database.

Data Synchronization

When Data is Synced

Data is automatically synced to your database in the following scenarios:

API Calls - When you call API endpoints, responses are synced
Webhooks - When webhooks are received, data is updated
Automatic Updates - Webhook events trigger updates for related entities

Manual Syncing

You can trigger syncs manually by calling API endpoints:

await corsair.gmail.api.messages.list({
    maxResults: 100,
});

await corsair.gmail.api.labels.list({});

See Database for more information about database concepts and querying patterns.

Gmail Database Schema

On this page