Gmail Integration

Lokus seamlessly integrates with Gmail, allowing you to import emails as notes, maintain threading context, and manage email-based tasks directly within your knowledge base. The integration uses OAuth 2.0 + PKCE for secure authentication and respects your privacy by processing emails locally.

Version: 1.3.1 | Status: Production Ready

Overview

The Gmail integration bridges your email workflow with your note-taking system, enabling you to capture important conversations, convert emails into actionable tasks, and reference email content alongside your notes without constantly switching between applications.

Key Features v1.3

-OAuth 2.0 + PKCE - Industry-standard secure authentication -Secure Token Storage - Keychain (macOS), Credential Manager (Windows) -Import emails as notes with full formatting preservation -Preserve threading and conversation context -Attachment handling with local storage and deduplication -Email search within Lokus using full-text search -Two-way sync (optional) with conflict resolution -Privacy-focused local processing, no cloud dependency -Offline Queue - Queue operations when offline, sync when back online -Auto-refresh tokens - Seamless token renewal without re-authentication -Hybrid redirect - Deep links + localhost fallback for auth

Setup

Connecting Gmail

Connect your Gmail account:

Initial Setup:

Open Settings → Integrations
Click “Connect Gmail”
Sign in with Google
Review permissions
Grant access
Confirm connection

Permissions Required:

Read email messages
Read email metadata
Search messages
Modify labels (optional)
Send email (optional, for two-way sync)

OAuth Authentication

Secure authentication flow:

Process:

Redirects to Google Sign-In
Choose Google account
Review requested permissions
Grant access
Return to Lokus
Connection established

Security:

OAuth 2.0 protocol
No password stored
Revokable access
Token encryption
Local token storage

Multiple Accounts

Connect multiple Gmail accounts:

Adding Accounts:

Settings → Integrations → Gmail
Click “Add Another Account”
Follow authentication flow
Select as default or alternate

Account Management:

Switch between accounts
Set default account
Remove accounts
Re-authenticate
View sync status

Importing Emails

Manual Import

Import individual emails:

Method 1: From Gmail

Open email in Gmail
Use Lokus browser extension
Click “Import to Lokus”
Choose destination folder
Configure import options
Import

Method 2: From Lokus

Open Gmail panel in Lokus
Browse or search emails
Select email
Click “Import as Note”
Email saved as note

Method 3: Forward to Lokus

Forward email to your Lokus email
Email auto-imported
Creates note in inbox folder
Preserves all content

Batch Import

Import multiple emails at once:

Process:

Gmail panel → Select emails
Shift+click for range
Cmd/Ctrl+click for multiple
Click “Import Selected”
Choose options
Import

Import Options:

Destination folder
Preserve labels as tags
Include attachments
Download inline images
Create links between thread emails

Automatic Import

Set up automatic email import:

Auto-import Rules:

rules:
  - condition: from:important@company.com
    action: import
    folder: /Work/Important
    tags: [email, important]
 
  - condition: label:project-alpha
    action: import
    folder: /Projects/Alpha
    tags: [project, email]
 
  - condition: subject:contains:"meeting"
    action: import
    folder: /Meetings
    template: meeting-notes

Configuration:

Settings → Gmail → Auto-import
Create new rule
Define condition
Set action
Enable rule

Email as Notes

Note Structure

Imported emails become structured notes:

---
type: email
email_id: msg_abc123
from: sender@example.com
to: recipient@example.com
cc: [cc1@example.com, cc2@example.com]
date: 2024-03-20T10:30:00Z
subject: Project Update
thread_id: thread_xyz789
labels: [inbox, important]
tags: [email, project]
---
 
# Project Update
 
**From:** John Doe <sender@example.com>
**To:** You <recipient@example.com>
**Date:** March 20, 2024 at 10:30 AM
**Thread:** [[Email Thread: Project Discussion]]
 
## Email Content
 
[Email body content preserved with formatting]
 
## Attachments
 
- [[Project_Document.pdf]]
- [[Screenshot.png]]
 
## Related
 
- [[Previous Email in Thread]]
- [[Project Notes]]
 
---
 
*Imported from Gmail on {{import_date}}*
*[View in Gmail](https://mail.google.com/mail/u/0/#inbox/msg_abc123)*

Email Metadata

Preserved email properties:

Standard Fields:

Message ID
Thread ID
From, To, CC, BCC
Subject
Date sent/received
Labels/categories
Read/unread status
Starred status

Custom Fields:

Import date
Gmail link
Attachments list
Thread position
Related notes

Threading

Email threads maintained:

Thread Features:

All thread emails linked
Thread overview note
Chronological order
Quick navigation
Thread visualization

Thread Note:

# Email Thread: Project Discussion
 
**Participants:** John, Sarah, Mike
**Messages:** 8
**Start Date:** 2024-03-15
**Last Updated:** 2024-03-20
 
## Thread Overview
 
Brief summary of conversation
 
## Messages
 
1. [[2024-03-15 Initial Question]] - John
2. [[2024-03-15 Response]] - Sarah
3. [[2024-03-16 Follow-up]] - John
4. [[2024-03-18 Update]] - Mike
5. [[2024-03-20 Final Decision]] - Sarah
 
## Related
 
- [[Project Plan]]
- [[Meeting Notes]]

Attachments

Attachment Handling

Email attachments managed:

Import Options:

Download All: Save all attachments locally
Download On-Demand: Download when clicked
Link Only: Keep in Gmail, link to it
Inline Images: Embed in note

Storage:

Stored in attachments folder
Organized by date or sender
Deduplicated
Searchable

Attachment Notes

Attachments become notes:

---
type: attachment
source: email
email_id: msg_abc123
filename: Document.pdf
size: 2.5 MB
mime_type: application/pdf
date: 2024-03-20
---
 
# Document.pdf
 
**From Email:** [[Project Update]]
**Sender:** sender@example.com
**Date Received:** 2024-03-20
 
## File Details
 
- **Size:** 2.5 MB
- **Type:** PDF
- **Pages:** 15
 
## Preview
 
[PDF preview or thumbnail]
 
## Related
 
- [[Email: Project Update]]
- [[Project Documentation]]
 
[Download](file://path/to/Document.pdf) | [View in Gmail](https://mail.google.com/...)

Email Search

Search Within Lokus

Search imported emails:

Search Syntax:

type:email
from:sender@example.com
to:recipient@example.com
subject:"project update"
email-date:>2024-03-01
has:attachment
label:important
thread:thread_xyz789

Search Features:

Full-text search in email body
Search by sender/recipient
Search by date
Search attachments
Search threads
Filter by labels

Gmail Search

Search Gmail directly from Lokus:

Gmail Search Panel:

Open Gmail panel
Use Gmail search syntax
Results load from Gmail
Preview in Lokus
Import if needed

Gmail Operators:

from:user@example.com
subject:meeting
has:attachment
after:2024/03/01
before:2024/03/31
is:unread
is:starred
label:work

Two-Way Sync

Sync Configuration

Enable bidirectional sync:

Sync Options:

One-way (Import Only): Gmail → Lokus
Two-way: Gmail ↔ Lokus
Selective: Specific labels/folders

Configuration:

Settings → Gmail → Sync
Choose sync mode
Select labels to sync
Set sync interval
Enable sync

Sync Behavior

How sync works:

Import (Gmail → Lokus):

New emails imported
Email updates synced
Label changes reflected
Attachments downloaded

Export (Lokus → Gmail):

Note changes sent to Gmail
Tags become labels
Content updates synced
Status changes reflected

Conflict Resolution:

Last write wins
Manual resolution option
Version history
Undo capability

Email Actions

Create Tasks from Email

Convert emails to tasks:

Quick Task Creation:

Select email note
Click “Create Task”
Task pre-filled from email
Set due date and priority
Task linked to email

Example Task:

- [ ] Review project document @john  2024-03-25 !high
  From: [[Email: Project Update]]
  Attachment: [[Project_Document.pdf]]
  Context: John sent the final draft for review

Reply from Lokus

Reply to emails (two-way sync enabled):

Reply Process:

Open email note
Click “Reply”
Compose response in editor
Send reply
Reply synced to Gmail

Reply Features:

Markdown formatting
Attachment support
Threading preserved
Draft saving
Template support

Email Labels

Manage Gmail labels:

Label Actions:

Add labels to email
Remove labels
Create new labels
Rename labels
Color labels

Label Sync:

Labels sync as tags
Tags sync as labels
Bidirectional updates
Custom mapping

Privacy and Security

Data Storage

Where email data is stored:

Local Storage:

Emails stored locally
Encrypted at rest
No cloud dependency
Full data control

Token Storage:

OAuth tokens encrypted
Secure key storage
OS keychain integration
No password storage

Privacy Controls

Control your data:

Privacy Options:

Disable sync
Delete imported emails
Clear cache
Revoke access
Export data

Data Retention:

Configure retention period
Auto-delete old emails
Archive options
Selective deletion

Permissions

Granular permission control:

Permission Levels:

Read-only (view emails)
Read and modify (manage labels)
Full access (send/receive)

Revoke Access:

Settings → Gmail → Accounts
Select account
Click “Revoke Access”
Confirm revocation
Access removed

Automation

Email Rules

Automate email handling:

Rule Types:

Auto-import by criteria
Auto-tag based on sender
Auto-create tasks
Auto-link to projects
Auto-archive

Example Rules:

# Client emails
- condition: from:client@company.com
  actions:
    - import: /Clients/Company
    - tag: client, important
    - create_task: "Review client email"
 
# Meeting invites
- condition: subject:contains:"meeting" AND has:calendar_invite
  actions:
    - import: /Meetings
    - apply_template: meeting-notes
    - extract_date_to_calendar
 
# Newsletters
- condition: from:newsletter@*
  actions:
    - import: /Reading/Newsletters
    - tag: newsletter, reading-list

Email Templates

Template-based email import:

Template Application:

Detect email type
Apply matching template
Extract key information
Structure as note
Link related content

Template Examples:

Meeting invites → Meeting notes
Bug reports → Issue tracker
Customer feedback → Feedback log
Receipts → Expense tracking

Mobile Support

Mobile Email Import

Import emails on mobile:

Mobile Features:

Share to Lokus (iOS/Android)
Quick import
Offline queuing
Sync when online

Share Sheet:

Open email in Gmail app
Tap Share
Select “Lokus”
Choose folder
Import

Configuration

Gmail Settings

Configure in Settings → Gmail:

General:

Connected accounts
Default account
Import folder
Attachment storage

Sync:

Sync mode (one-way/two-way)
Sync interval
Labels to sync
Conflict resolution

Privacy:

Data retention
Cache settings
Encryption
Analytics

Advanced:

API rate limits
Batch size
Retry logic
Debug logging

Keyboard Shortcuts

Action	Shortcut
Open Gmail Panel	Cmd/Ctrl + Shift + G
Import Selected	Cmd/Ctrl + I
Create Task from Email	Cmd/Ctrl + Shift + T
Reply to Email	R
Forward Email	F
Archive Email	E
Search Gmail	Cmd/Ctrl + Shift + F

Integration Examples

Project Management

Link emails to projects:

Workflow:

Import project-related emails
Auto-tag with project name
Link to project note
Create tasks from action items
Track in project dashboard

Client Communication

Track client conversations:

Setup:

Folder per client
Auto-import client emails
Thread visualization
Task creation for follow-ups
Timeline view

Meeting Preparation

Prepare using emails:

Process:

Import meeting invite
Extract attendees and agenda
Gather related emails
Create meeting note
Link all context

Troubleshooting

Common Issues

Issue: Authentication failed Solution: Re-authenticate, check permissions, verify account

Issue: Emails not importing Solution: Check sync settings, verify connection, review rules

Issue: Attachments not downloading Solution: Check storage space, verify permissions, retry download

Issue: Sync conflicts Solution: Review conflict resolution, check modification times

Re-authentication

Refresh Gmail connection:

Process:

Settings → Gmail → Accounts
Select account showing error
Click “Re-authenticate”
Sign in again
Grant permissions
Connection restored

Best Practices

Email Organization

Effective Practices:

Use labels in Gmail for auto-import
Create folder structure in Lokus
Regular email cleanup
Archive old emails
Link related content

Import Strategy

Selective Importing:

Don’t import everything
Focus on important emails
Use filters liberally
Regular review of imported emails
Prune unnecessary imports

Next Steps

Use Templates for email import
Create Tasks from emails
Link emails in Wiki Links
Search emails with Search System

Image Viewer Themes & Customization