How to Import Gmail and QQ Mail into Obsidian with an Email Importer Plugin

✨ Before We Start

Most people have this exact problem:

• invoices stay in email
• order confirmations stay in email
• project discussions stay in email
• useful newsletters stay in email
• security alerts stay in email

After a while, the inbox becomes a place where everything exists, but nothing feels truly organized.

The real problem is not receiving email. The real problem is this:

important information stays trapped in the inbox instead of becoming part of your knowledge system.

That is why I built this small Obsidian email importer plugin.

Its goal is simple:

📥 pull Gmail and QQ Mail into Obsidian and save them as Markdown notes.

I do not want this post to feel like dry product documentation. I want it to feel practical.

So in this guide, I will walk through:

• what the plugin actually does
• what happens after installation
• how to configure Gmail and QQ Mail
• why Gmail uses an App Password
• why QQ Mail uses an authorization code
• which settings are safest for a first run
• what to check first when something fails

If you are completely new to IMAP or mailbox authorization, that is fine. You can still follow this step by step. 🙌

📌 What This Plugin Actually Does

In one sentence:

it connects to your mailbox over IMAP and writes selected emails into Obsidian as Markdown files.

That means you do not have to:

• manually copy email content
• create a new note for every message
• reformat the same kind of information again and again

The plugin takes over the repetitive part. You only need to decide:

• which mailbox to connect
• what should be synced
• what is worth keeping long term

This creates a nice division of work:

• 📮 email handles incoming messages
• 🧠 Obsidian handles long-term organization
• ✍️ you decide what is actually valuable

🚀 What the Current Version Can Do

The current version already supports:

• ✉️ Gmail import
• ✉️ QQ Mail import
• 🔌 connection testing
• 📥 importing unread mail or all mail
• ♻️ duplicate prevention
• 📂 automatic folder creation
• 🛠️ custom root-folder support
• 🗂️ separate output folders for different accounts
• ⚡ one-click sync from inside Obsidian

If you remember only one thing, remember this:

new email can become structured notes inside your vault automatically.

That is the real value here. Not “moving the inbox,” but turning useful email into reusable knowledge.

🗂️ What Folder Structure Gets Created

If you enable automatic standard-folder creation, the plugin will build a basic email workspace for you.

Default root folder:

个人笔记/邮件入库

Default subfolders:

个人笔记/邮件入库/待整理
个人笔记/邮件入库/账单凭证
个人笔记/邮件入库/项目沟通
个人笔记/邮件入库/账号通知
个人笔记/邮件入库/精华摘要

This is useful because it gives you structure immediately:

• less clutter on day one
• easier archiving later
• cleaner search and Dataview filtering

If you prefer a different naming style, you can also change the root folder, for example:

Email System
Inbox/Email
Mail Archive

🔧 How to Install and Enable It

The setup is straightforward.

Step 1: Put the plugin inside your Obsidian plugins folder

Plugin folder name:

obsidian-email-importer

Step 2: Open Obsidian

Go to:

Settings → Community plugins

Step 3: Disable Restricted mode if it is still enabled

Otherwise community plugins will not load.

Step 4: Enable the plugin

Find:

Email Importer

and turn it on.

Step 5: Open the plugin settings

Once enabled, open its settings page and start configuring your mailboxes.

⚙️ What the Main Settings Mean

A lot of people do not get stuck on installation. They get stuck on the settings.

So here is the plain-English version.

1) Output Folder

This is the:

global default output folder

If an account does not define its own output folder, imported mail goes here.

Typical default:

个人笔记/邮件入库/待整理

That is a good choice if you want everything to land in one place first.

2) Standard Root Folder

This is the root folder used when the plugin auto-creates the standard folder structure.

Typical value:

个人笔记/邮件入库

If you change it to:

邮件系统

the plugin will create:

邮件系统/待整理
邮件系统/账单凭证
邮件系统/项目沟通
邮件系统/账号通知
邮件系统/精华摘要

3) Auto-create Standard Folder Structure

This switch means:

automatically create the standard folders when the plugin loads

My recommendation:

On

It is the easiest option for beginners.

4) Create Standard Folders Now

This is a manual trigger.

Use it when:

• you just changed the root folder
• you want the folders created immediately
• you are not sure whether creation worked earlier

5) Default Category

This is the default category written into the note frontmatter.

A good starter value is:

待整理

That makes later filtering, Dataview views, and batch cleanup much easier.

6) Summary Length

This controls:

how many characters of the email body are kept for the summary

Useful starter values:

300
500
800

If your emails are often long, I would start with:

500

That is a good middle ground.

📨 What the Per-Account Settings Mean

Gmail and QQ Mail both use almost the same structure. Once you understand one, the rest becomes easy.

1) Enable

Controls whether this account participates in sync.

If it is off:

• the plugin ignores that account

2) Display Name

This is mainly for your own clarity.

You can use names like:

Gmail
QQ Mail
Work Mail
Study Mail

It does not affect the connection itself. It only helps you keep the settings readable.

3) IMAP Host

Mailbox server address.

Gmail:

imap.gmail.com

QQ Mail:

imap.qq.com

Usually, do not change these.

4) Port

Recommended value:

993

That is the common secure IMAP port.

5) Username

Use your full email address here.

For example:

yourname@gmail.com
123456789@qq.com

Do not use:

• a nickname
• a label
• only the part before @

6) Password / Authorization Code

This is the setting people get wrong most often. ⚠️

In most cases:

• Gmail should not use your normal Google login password
• QQ Mail should not use your normal login password either

Use:

Gmail: App Password
QQ Mail: authorization code

That difference matters a lot.

7) Folder

This tells the plugin which mailbox folder to read from.

Default:

INBOX

If you do not have a special reason, keep it there.

8) Account-specific Output Folder

This is very useful if you want to separate different accounts.

For example:

Gmail → 个人笔记/邮件入库/Gmail
QQ邮箱 → 个人笔记/邮件入库/QQ邮箱

If left empty, the plugin falls back to the global output folder.

9) Search Condition

This controls which emails get synced.

Common values:

UNSEEN
ALL

Meaning:

• UNSEEN: sync unread messages only
• ALL: sync everything

For the very first run, I strongly recommend:

UNSEEN

Why?

• safer
• easier to test
• less likely to flood your vault immediately

10) Max Emails Per Sync

This controls how many emails are imported in one sync.

Beginner-friendly starting values:

5
10

Do not start huge. First make sure everything works smoothly.

11) Mark as Read After Sync

This controls:

whether imported messages are marked as read in the mailbox afterward

For your first run, I recommend:

Off

That keeps your original mailbox state untouched.

12) Test Connection

This button matters a lot.

Best order:

1. fill in the settings
2. click Test Connection
3. only sync after it succeeds

That one habit saves a lot of troubleshooting time.

📮 How to Set Up Gmail

If you want to configure Gmail first, use:

IMAP host: imap.gmail.com
Port: 993
Username: your Gmail address
Password: Google App Password
Folder: INBOX
Search: UNSEEN

The key point here is:

Gmail usually should not use your normal Google password for this. Use an App Password instead.

🔐 How to Get a Gmail App Password

Short version:

turn on Google 2-Step Verification first, then generate an App Password.

Requirement

You must enable:

2-Step Verification

Basic path

1. Sign in to your Google account
2. Open the Security section
3. Turn on 2-Step Verification
4. Open:

App passwords

5. Generate a new 16-character password
6. Paste it into the plugin password field

So what you really enter into the plugin is:

Gmail → Password / Authorization Code → 16-character App Password

If you cannot see “App passwords”

Common reasons:

• 2-Step Verification is not enabled yet
• it is a work or school-managed account
• Advanced Protection is enabled
• your organization blocks this kind of access

Can I just use my Gmail login password?

Usually:

• ❌ not recommended
• ❌ often it will simply fail

So do not waste too much time trying the normal password first.

📫 How to Set Up QQ Mail

For QQ Mail, use:

IMAP host: imap.qq.com
Port: 993
Username: your QQ Mail address
Password: QQ Mail authorization code
Folder: INBOX
Search: UNSEEN

The same warning applies here:

QQ Mail usually expects an authorization code, not your normal login password.

🧾 How to Get a QQ Mail Authorization Code

Short version:

enable IMAP/SMTP in QQ Mail first, then generate the authorization code.

Typical path inside the QQ Mail web interface:

1. Sign in at https://mail.qq.com
2. Open Settings
3. Go to Account
4. Find POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV services
5. Enable IMAP/SMTP
6. Complete phone or security verification
7. Generate the authorization code
8. Paste it into the plugin password field

What you should enter is:

QQ Mail → Password / Authorization Code → authorization code

Three quick reminders:

• it is not your QQ login password
• verification by phone is often required
• if the code expires, just generate a new one

✅ Recommended Beginner Setup

If you want the safest first-run configuration, start here.

Gmail

Enable: On
Display name: Gmail
IMAP host: imap.gmail.com
Port: 993
Username: your Gmail address
Password: App Password
Folder: INBOX
Account-specific output folder: 个人笔记/邮件入库/Gmail
Search: UNSEEN
Max emails per sync: 5
Mark as read after sync: Off

QQ Mail

Enable: On
Display name: QQ Mail
IMAP host: imap.qq.com
Port: 993
Username: your QQ Mail address
Password: QQ Mail authorization code
Folder: INBOX
Account-specific output folder: 个人笔记/邮件入库/QQ邮箱
Search: UNSEEN
Max emails per sync: 5
Mark as read after sync: Off

Why this setup works well:

• ✅ it avoids importing too much at once
• ✅ it does not disturb your mailbox read state
• ✅ it is easier to roll back if something looks wrong

▶️ How to Start Using It

I recommend this order:

Step 1: Fill in Gmail and/or QQ Mail settings

Do not sync yet. Just make sure everything is complete.

Step 2: Click Test Connection first

If the connection test fails, syncing probably will not go well either.

Step 3: Start sync

Or run the Obsidian command:

Sync Gmail / QQ Mail into the vault

Step 4: Review the imported notes

Check:

• whether filenames look reasonable
• whether categories look right
• whether content is duplicated

That quick review is worth doing every time you test a new mailbox.

🧪 My Strong Advice for the First Run

For your first run, keep it conservative:

Search: UNSEEN
Max emails per sync: 5
Mark as read after sync: Off

Why?

Because this setup:

• avoids importing a huge backlog immediately
• keeps the original mailbox state intact
• makes mistakes easier to undo

A simple rule to remember:

on the first run, prioritize safety over speed.

🛠️ Common Troubleshooting

1) Test Connection failed

Check these first:

• is the email address complete
• is the App Password / authorization code correct
• is Gmail 2-Step Verification enabled
• is IMAP/SMTP enabled in QQ Mail
• are the host and port correct

Very often, the plugin is fine. The issue is just the authorization input.

2) Why is no email being imported?

Check:

• is the search condition too strict
• is the folder really INBOX
• did you choose unread-only sync when there are no unread messages

3) Why are fewer emails imported than expected?

Usually because of one of these:

• search-condition limits
• max-import limits
• duplicate prevention

And honestly, that is often a good thing. It means the plugin is not blindly dumping everything.

4) Why do I recommend turning off “Mark as Read After Sync” at first?

Because it is the safest option.

Especially during testing, you may not be sure yet:

• whether the import looks right
• whether anything duplicates
• whether this changes your normal email workflow

So keep read state untouched until you trust the setup.

💡 The Best Way to Use This in Real Life

What I recommend is not:

import everything forever without thinking

What I recommend is:

1. import automatically
2. review manually
3. keep only what is worth retaining

That gives you a much healthier system:

• email keeps doing email things
• Obsidian becomes the place for long-term knowledge
• your vault does not turn into a second junk inbox

Once that boundary is clear, the whole workflow feels much better. 🧠

✅ Final Summary

If you only want the essentials, remember these lines:

Gmail uses an App Password
QQ Mail uses an authorization code
Test the connection first
Then start syncing
For the first run, use UNSEEN + 5 emails
Keep “Mark as Read After Sync” turned off at first

The real purpose of this plugin is not just “email import.” It is this:

turn useful email into durable notes inside Obsidian.

If you already treat Obsidian as a personal knowledge base, this is one of those small upgrades that can make the whole system feel much more alive. 📮➡️📝

References

• Google official App Password help
  https://support.google.com/accounts/answer/185833
• Google official App Password troubleshooting
  https://support.google.com/accounts/answer/2461835
• Google Workspace IMAP / App Password guidance
  https://support.google.com/a/answer/9003945
• Huawei support article referencing the QQ Mail authorization-code setup path
  https://consumer.huawei.com/cn/support/content/zh-cn15872097