IMAP IDLE运行时新邮件无响应问题排查（Python）

问题概述 #

使用Python 3.10编写IMAP IDLE脚本，语法合规可编译，通过IMAPClient/imap_tools库能正常访问收件箱、读取邮件主题/日期，但处于IDLE状态时，收到新邮件服务器无任何数据返回。测试过gmail.com、yahoo.com、outlook.com三个邮箱均无效。需确认：

• 此现象是否为IMAP IDLE正常表现？
• 是否需在Outlook中配置相关设置？
• 代码语法是否存在错误？
• 推荐支持读取新邮件、下载附件的库（已知IMAPClient不支持附件下载）

通用变量 #

# Naturally, these are not actual values used
HOST = 'imap.outlook.com'
USER = 'address@domain.com'
PASS = 'password'

测试代码 #

IMAPClient版本

from imapclient import IMAPClient

server = IMAPClient(HOST)
server.login(USER, PASS)
server.select_folder("INBOX")

# Start IDLE Mode
server.idle()
while True:
    try:
        responses = server.idle_check(timeout=30) # IDLE for 30 seconds
        print("Server sent:", responses if responses else "nothing")
    except KeyboardInterrupt:
        break
server.idle_done()
print("\nIDLE mode done")
server.logout()

imap_tools示例1

from imap_tools import MailBox, A

with MailBox(HOST).login(USER, PASS) as mailbox:

    mailbox.idle.start()
    responses = mailbox.idle.poll(timeout=60) # IDLE for 60 seconds
    mailbox.idle.stop()

    if responses:
        for msg in mailbox.fetch(A(seen=False)):
            print(msg.date, msg.subject)
    
    else:
        print('No new emails')

imap_tools示例2

import time, socket, imaplib, traceback
from imap_tools import A, MailBox, MailboxLoginError, MailboxLogoutError

done = False

while not done:
    connection_start_time = time.monotonic()
    connection_live_time = 0.0
    try:
        with MailBox('imap.outlook.com').login(USER, PASS, 'INBOX') as mailbox:
            print('@@ new connection', time.asctime())

            while connection_live_time < 29 * 60:
                try:
                    responses = mailbox.idle.wait(timeout=3 * 60)
                    print(time.asctime(), 'IDLE responses:', responses)

                    if responses:
                        for msg in mailbox.fetch(A(seen=False)):
                            print('->', msg.date, msg.subject)
                except KeyboardInterrupt:
                    print('~KeyboardInterrupt')
                    done = True
                    break
                connection_live_time = time.monotonic() - connection_start_time

    except (TimeoutError, ConnectionError, imaplib.IMAP4.abort, MailboxLoginError, MailboxLogoutError, socket.herror, socket.gaierror, socket.timeout) as e:
            
        print(f'## Error\n{e}\n{traceback.format_exc()}\nReconnecting in a minute. . .')
        time.sleep(60)

排查与解决 #

1. 代码语法修正 #

IMAPClient代码优化

当前代码仅打印IDLE响应，未触发新邮件拉取，但无响应的核心问题不在此。需注意：idle_check超时后返回空列表，若有新邮件，服务器会主动推送EXISTS/RECENT响应，此时idle_check会立即返回结果。可在收到响应后添加邮件拉取逻辑：

# 原循环内修改
responses = server.idle_check(timeout=30)
if responses:
    # 拉取新邮件
    messages = server.search(['UNSEEN'])
    for msg_id in messages:
        print(server.fetch(msg_id, ['SUBJECT', 'DATE']))

imap_tools代码优化

示例1为单次IDLE查询，易错过新邮件；示例2逻辑更健壮，但收到响应后可尝试刷新文件夹确保能读取新邮件：

# 在if responses:块内添加
mailbox.folder.set('INBOX')  # 刷新文件夹
for msg in mailbox.fetch(A(seen=False)):
    print('->', msg.date, msg.subject)

2. 账户设置要求（关键） #

无响应大概率是邮箱IMAP权限或验证方式问题，三个邮箱需分别配置：

• Gmail：
  1. 开启IMAP：设置→转发和POP/IMAP→启用IMAP
  2. 若开启两步验证，需生成应用专用密码替代原密码登录
• Outlook.com：
  1. 开启IMAP：设置→邮件→同步电子邮件→启用IMAP选项
  2. 工作/学校账户需联系管理员确认IMAP访问未被禁用
• Yahoo：
  1. 开启IMAP：设置→更多设置→邮件账户→IMAP→启用
  2. 生成应用专用密码（账户安全→应用密码）

3. IMAP IDLE正常表现说明 #

IMAP IDLE的正常行为是：当邮箱有新邮件或状态变更（如邮件被标记已读）时，服务器会主动推送EXISTS/RECENT命令，客户端的idle_check/wait会立即返回响应。完全无响应不属于正常表现，排除代码问题后优先检查账户权限。

4. 推荐附件下载库 #

imap_tools（优先推荐）

语法简洁，原生支持附件解析与下载，示例：

from imap_tools import MailBox, A

with MailBox(HOST).login(USER, PASS) as mailbox:
    # 拉取未读邮件并下载附件
    for msg in mailbox.fetch(A(seen=False)):
        print(f"处理邮件：{msg.subject}")
        for att in msg.attachments:
            with open(f"附件_{att.filename}", 'wb') as f:
                f.write(att.payload)

imaplib（原生库）

无需额外安装，灵活性高但语法繁琐，需手动解析MIME结构：

import imaplib
import email
from email.policy import default

# 连接服务器
mail = imaplib.IMAP4_SSL(HOST)
mail.login(USER, PASS)
mail.select('INBOX')

# 搜索未读邮件
_, data = mail.search(None, 'UNSEEN')
for num in data[0].split():
    _, msg_data = mail.fetch(num, '(RFC822)')
    msg = email.message_from_bytes(msg_data[0][1], policy=default)
    print(f"邮件主题：{msg['subject']}")
    # 遍历并保存附件
    for part in msg.walk():
        if part.get_content_disposition() == 'attachment':
            filename = part.get_filename()
            if filename:
                with open(filename, 'wb') as f:
                    f.write(part.get_payload(decode=True))

mail.logout()

内容的提问来源于stack exchange，提问作者Shock