JavaMail邮件系统实战：SMTP/POP3/IMAP协议与收发附件全解析

简介：基于JavaMail电子邮件系统设计的课程设计报告PDF，面向软件工程、计算机相关专业学生以及需要实现邮件收发功能的Java开发者。资源完整呈现邮件系统的分析、设计与实现链路，从SMTP发送协议、POP3/IMAP接收协议到MIME附件扩展均有原理说明，可帮助厘清各协议在实际收发链路中的分工，并逐个讲解Session、Store、Folder、Message、Address、Transport等JavaMail API核心类的作用与调用关系。内容涉及客户端登录、邮件发送、邮件接收、邮件管理、附件发送等功能的总体框架与模块划分，同时给出电子邮件服务器端与客户端协作流程，可直接作为课程设计或毕业设计的参考方案。资源包仅含1个PDF文件，大小1.97MB，内容紧凑适合通读。已有415人学习浏览，适合正在完成邮件系统设计任务、希望快速掌握JavaMail工作原理并搭建系统框架的读者。

1. JavaMail电子邮件系统这套源码包，把SMTP发送、POP3接收、附件流程都串起来了

先说说这份资源是什么。它是一份 2009 年的软件工程课程设计报告，主题就是「电子邮件系统设计」，随报告一起提供的还有可运行的源文件。很多人一看到课程设计报告就以为是纯理论文档，实际上这份材料把 JavaMail 开发邮件的完整路径都走了一遍：系统分析、协议选型、UML 建模、模块划分、核心代码示例，最后落到 B/S 结构下的 JSP 页面实现。对于一个需要快速理解 JavaMail 收发邮件全流程的开发者来说，它比翻官方文档要省力得多——官方文档告诉你每个类怎么用，这份报告告诉你这些类在一个真实系统里是怎么组织在一起的。适合三类人：正在做 JavaWeb 课程设计的学生，刚接手邮件发送需求的企业开发者，以及想梳理 SMTP、POP3、IMAP 到底怎么协同工作的后端工程师。

2. JavaMail核心类与五步初始化：先让Session、Store、Folder各司其职

2.1 javax.mail 五个核心类的分工，别把职责搞混了

JavaMail API 的设计思路很清晰，它把邮件通信拆成了几个层次，分别用不同的类来承担。刚开始接触的人最容易犯的错就是把 Session 当成连接工具、把 Transport 当成唯一的入口，结果代码越写越乱。其实这些类的分工非常明确：Session 是会话上下文，负责持有全局配置；Store 代表邮件服务器上某个用户的存储空间；Folder 是存储空间里的邮件夹，也就是我们常说的 inbox、Sent 这类目录；Message 是一封邮件的抽象；Transport 才是真正把邮件推出去的传输通道。

这套分层的好处在于收发逻辑彻底解耦。发送邮件时你只需要 Session 和 Transport，接收邮件时用 Store 和 Folder，两者之间没有强依赖。报告里也用类框图把这几个类的关系画了出来，对照着看会更容易理解：Store 通过 Session 获得，Folder 从 Store 获得，Message 从 Folder 读取或创建，Transport 则独立负责发送。

通过可获得 Store 对象，参数 protocol 指定接收协议。步骤（4）调用 Store 的 connect() 方法连接接收服务器，参数是主机名、用户名和口令。这四步做完，你就已经站在邮箱门口了，下一步是打开具体的邮件夹。

为什么这套初始化流程值得记？因为几乎所有 JavaMail 收发操作的骨架都长这样。无论你是用 Gmail、QQ 邮箱还是自建邮服，变的无非是协议和主机参数，骨架不会变。把这份代码存成模板，后面开发任何邮件功能都能直接复用。

2.3 打开inbox邮件夹并读取邮件：READ_ONLY模式与第一封邮件

连接上 Store 之后，接下来的操作就是进入邮件夹。报告里的代码展示了最典型的读信流程，代码如下：

// 获得名为"inbox"的邮件夹 Folder folder = store.getFolder("inbox"); // 打开邮件夹 folder.open(Folder.READ_ONLY); // 获得邮件夹中的邮件数目 System.out.println("You have " + folder.getMessageCount() + " messages in inbox."); // 获得邮件夹中的未读邮件数目 System.out.println("You have " + folder.getUnreadMessageCount() + " unread messages in inbox."); // 从邮件夹中读取第一封邮件 Message msg = folder.getMessage(1); System.out.println("------the first message in inbox-------"); // 获得邮件的发送者、主题和正文 System.out.println("From: " + msg.getFrom()[0]); System.out.println("Subject: " + msg.getSubject()); System.out.println("Text: " + msg.getText());

这里有两个参数值得展开。第一个是 Folder.READ_ONLY，打开模式分成只读和可读写两种，如果你的业务只是展示邮件列表，用只读模式足够，而且能避免误删。如果要实现删除或移动邮件，必须用 Folder.READ_WRITE。第二个是 getMessage(1)，注意这个编号从 1 开始，不是从 0 开始，很多从数组思维转过来的人在这里翻过车。

另外注意 msg.getFrom() 返回的是 Address[] 数组，不是单个 Address。邮件头里 From 字段在极少数情况下会有多个地址，直接调用 getFrom()[0] 取第一个是没问题的，但要意识到这是一个数组。

3. SMTP / POP3 / IMAP / MIME 的选型逻辑：发信收信协议怎么搭配最合适

3.1 三个核心协议的边界：SMTP只管发，POP3和IMAP管收

很多新手搞不清楚邮件协议之间的关系，以为 SMTP、POP3、IMAP 是三选一的关系。实际上它们根本不冲突：SMTP 是发送通道，POP3 和 IMAP 是接收通道，两者搭配使用才构成完整的收发闭环。报告里讲得很明确：发送邮件服务器也叫 SMTP 服务器，接收邮件服务器叫 POP3 服务器或 IMAP 服务器，取决于你用了哪个接收协议。

POP3 的特点是简单、离线友好。邮件客户端通过 POP3 把服务器上的邮件下载到本地，下载后邮件通常就从服务器上删除了。这个模型适合单设备场景——你只需要在一台电脑上看邮件。代价是你换了设备就看不到历史邮件，因为服务器上已经没有了。

IMAP 则完全相反，它比 POP3 更强的地方在于邮件始终保留在服务器上。你可以在手机上读邮件摘要，在电脑上下载附件，在家里的旧笔记本上归档邮件，所有设备看到的都是同一份邮件状态。报告里列出了 IMAP4 的几个关键特性：摘要浏览邮件、选择性下载附件、把服务器邮箱当存储工具。换句话说，IMAP 是现代多设备同步场景的默认选择。

具体选哪个，可以按下面的标准来判断：如果你做的是企业内部的邮件归档系统，选 IMAP；如果你做的是轻量级客户端，只要求把邮件拉下来本地展示，POP3 就够了；如果你只是给现有系统加一个发邮件的功能，那么你只需要 SMTP，根本不需要操心接收协议。这里我用一张表来总结：

3.2 MIME规范约束下的邮件组装：正文和附件的容器

MIME 本身不是传输协议，它是邮件格式的规范。RFC822 时代规定邮件内容只能是 ASCII 纯文本，这显然满足不了今天发图片、发 Word 文档的需求。MIME 在 RFC822 的基础上做了扩展，允许邮件正文包含多种类型的内容，也允许携带附件。报告里特别强调了一点：按照 MIME 规范，电子邮件由邮件头和正文两部分组成，邮件头包括日期、发件人地址、收件人地址和主题，正文部分可以是普通文本，也可以包含一个或多个附件。

落到 JavaMail 上，所有 MIME 相关的操作都由 MimeMessage 类承载。它提供了 setSubject(String) 设置主题、setHeader(String name, String value) 设置自定义头部、setContent(Object o, String type) 设置正文内容和类型。注意第三个方法的 type 参数，它指定的是 MIME 类型，比如 "text/plain" 还是 "text/html"。如果你要发 HTML 格式的邮件，就在这里把类型设为 "text/html"，而不是调用 setText()。

3.3 协议组合的实际配置示例：一份标准勘验的 Properties

理解了协议边界之后，配置就变得非常直观。报告给出了 JavaMail 初始化时设置 Properties 的标准代码，这也是我每次写邮件模块都会抄一遍的骨架：

Properties props = new Properties(); // 指定邮件发送协议 props.put("mail.transport.protocol", "smtp"); // 指定邮件接收协议 props.put("mail.store.protocol", "imap"); // 指定支持SMTP协议的Transport具体类 props.put("mail.smtp.class", "com.sun.mail.smtp.SMTPTransport"); // 指定支持IMAP协议的Store具体类 props.put("mail.imap.class", "com.sun.mail.imap.IMAPStore"); // 指定邮件发送服务器的IP地址或主机名 props.put("mail.smtp.host", hostname);

这段代码里 transport.protocol 和 store.protocol 可以同时存在，因为它们是两个通道，互不干扰。mail.smtp.class 和 mail.imap.class 这两行允许第三方实现类替换官方实现，一般不轻易动。真正需要频繁调整的是 mail.smtp.host—— 换个邮件服务商就要改这个值。

还有一个容易被忽视的配置是 mail.smtp.auth。文档时代很多邮服允许匿名发信，但现在的公共邮服几乎都要求认证，所以实际项目里还需要追加 props.put("mail.smtp.auth", "true")。报告后面的模块划分里也提到了 SMTP 验证是大部分邮件服务器的基本要求，这一点在真实开发中甚至能决定你的邮件能不能发出去。

4. B/S架构下五个模块的落地细节：登录、收发、附件、文件夹管理如何拆

4.1 登录模块：Merak Mail Server的账户验证和session传递

整个系统采用 B/S 架构，以 Tomcat 作为 Web 服务器和 JSP/Servlet 容器，登录模块由 login.jsp 完成。报告特别提到，实验环境使用的是 Merak Mail Server 搭建的邮件服务器，预先创建了两个测试账户，只有使用正确的邮件地址和密码才能登录成功。

登录完成后，系统会把用户 ID 保存到 session 变量中，并传递给后续的收发模块。这里有一个设计上的细节：登录模块不只是验证密码，还要把用户选中的接收协议和服务器信息一并记录下来，因为后续连接 Store 时还要用到这些参数。如果你自己动手改这份代码，建议在 session 里同时存一个对象，而不是散存多个字段。比如存一个 LoginUser 对象，包含邮箱地址、接收服务器主机名、协议类型，后面取用就方便很多。

4.2 接收邮件与附件：showmessage.jsp的分页列表和附件保存

接收模块由 showmessage.jsp 完成，核心操作是连接 Store、打开用户的 inbox 邮件夹，然后把邮件列表分页显示在网页上。在这个模块里，报告代码中用 PMessage 类对 Message 做了重新封装：原来的 Message.getTo() 返回 Address[] 数组，封装后可以返回字符串类型的地址，更方便在 JSP 页面上直接输出。

这个封装思路值得记下来。JavaMail 的 API 面向的是协议操作，返回的数据结构不一定适合网页渲染。比如邮件的发送时间返回的是 Date 类型，如果要在页面上按固定格式展示，就需要自己做格式化；邮件正文的 MIME 类型不同，展示逻辑也不同。PMessage 这种包装类相当于一张只读 DTO（数据传输对象），隔离了 JavaMail API 和页面模板之间的差异。

附件保存是这个模块里比较容易出问题的地方。流程是：遍历 Message 的 BodyPart，判断每个 Part 的 disposition 是否为 Attachment，是的话就调用 Part.getInputStream() 拿到数据流，然后写入本地文件。这里必须注意不要直接把 Part.getFileName() 拿来做文件名，因为中文文件名经过编码后是一串乱码，需要先解码。具体怎么处理，后面避坑章节会展开讲。

4.3 发送与回复邮件：compose.jsp的正文编写和附件上传

发送模块由 compose.jsp 完成，负责编写新邮件和上传附件。发送流程是：用户填写收件人地址、主题、正文，点击发送后，后台构造 MimeMessage 对象，设置 RecipientType.TO、主题、正文，然后调用 Transport.send() 发送。回复邮件的逻辑基本复用发送模块，只是收件人会主动填充为原邮件的发件人，主题前缀加上 Re:。

这里的核心考点是附件的处理。发送带附件的邮件时，需要创建一个 MimeMultipart 对象，把正文作为一个 MimeBodyPart 添加进去，再把每个附件作为独立的 MimeBodyPart 添加进去，最后通过 msg.setContent(multipart) 设置整个邮件内容。代码骨架是：

MimeMultipart multipart = new MimeMultipart(); // 正文部分 MimeBodyPart textPart = new MimeBodyPart(); textPart.setText("这是邮件正文"); multipart.addBodyPart(textPart); // 附件部分 MimeBodyPart attachmentPart = new MimeBodyPart(); attachmentPart.attachFile(new File("C:/report.pdf")); multipart.addBodyPart(attachmentPart); // 设置多部分内容 msg.setContent(multipart);

这段代码里两个值得注意的参数：MimeBodyPart.attachFile(File) 是从本地文件构造附件；setContent(multipart) 会自动识别 multipart 的 content type，不需要手动指定 MIME 类型。如果是网页应用里用户上传的文件，则应该用 bodyPart.setDataHandler(new DataHandler(vo)) 的形式，其中 vo 是临时文件对象。

4.4 邮件处理与文件夹管理：删除、保存和自建文件夹

邮件处理模块由 listonefoldr.jsp 完成，提供显示邮件列表、删除选中的邮件、显示错误信息三个功能。删除的逻辑需要用到 Folder 的读写模式：只有以 READ_WRITE 模式打开时才能调用 msg.setFlag(Flags.Flag.DELETED, true) 和 folder.expunge() 真正删除邮件。光 setFlag 不 expunge，邮件只是被标记为删除，不会物理移除。

文件夹管理模块稍微进阶一些，支持用户新建邮件夹、重命名、删除自己创建的文件夹。在 IMAP 协议下，Folder.getFolder("自定义名称") 即可创建子目录。要注意的是，inbox 是保留邮件夹，用户不能删除，报告里特别强调了这一点，这也是协议层面的约束，不是代码逻辑能绕开的。实现时需要对非 inbox 的文件夹做 create、rename、delete 操作，并对 inbox 做保护性判断。

5. JavaMail上手避坑清单：从中文乱码到资源泄漏的五个真实场景

5.1 中文主题显示乱码

现象：发送的邮件主题是中文，对方收到后显示一串问号或乱码。

原因：MimeMessage.setSubject(String subject) 内部默认没有指定字符集，中文被按照平台默认字符集编码，对方的邮件客户端按照另一种字符集解码，两边不一致就乱了。

解决：强制指定编码，调用 msg.setSubject("你的主题", "UTF-8")，宽度使用同样的方式处理正文 setText("正文", "UTF-8")。如果主题里有特殊字符，还需要先经过 MimeUtility.encodeText(subject, "UTF-8", "B") 做编码处理。

5.2 附件文件名乱码

现象：收到的附件文件名全是 =?UTF-8?B?...?= 这样的形式，或者下载后文件名变成随机串。

原因：attachFile 方法设置了文件对象，但文件名没有经过 MIME 编码。RFC 2047 规定，非 ASCII 字符的文件名必须用 encoded-word 格式传输。

解决：使用 Part.setFileName(MimeUtility.encodeText(originalFilename, "UTF-8", "B")) 显式编码文件名。读取时用 MimeUtility.decodeText(part.getFileName()) 解码回来。两端都做了编码和解码，就不会再出现文件名乱码。

5.3 连接邮箱服务器超时或握手失败

现象：程序启动后卡在 store.connect() 或者 Transport.send() 很长一段时间，然后抛出 SocketTimeoutException 或 ConnectionException。

原因：JavaMail 默认的 timeout 值是无限大，网络不通或服务器响应慢时，程序会一直挂住。另外很多服务器要求显式声明 mail.smtp.auth，不声明会直接拒绝。

解决：在 Properties 里追加配置。

props.put("mail.smtp.connectiontimeout", "5000"); props.put("mail.smtp.timeout", "5000"); props.put("mail.smtp.auth", "true");

类似地，接收协议也有对应的 timeout 配置 mail.imap.connectiontimeout。这四行配置在本地调试时看不出差别，部署到线上环境几乎是必加的。

5.4 使用邮件时抛出 FolderClosedException

现象：第一次打开邮件夹读取正常，第二次再读取同一个 folder 实例时抛出 FolderClosedException。

原因：Store 或 Folder 的连接被关闭后，原有的引用并没有自动失效。常见原因是 session 的连接因为超时被服务端断开，或者上一次操作后没有正确保持连接。

解决：每次操作前检查 folder.isOpen()，如果返回 false 就重新调用 folder.open()。如果业务上频繁收发，通常会在一个请求周期内打开、操作、关闭，不要长期持有 Folder 实例。这个问题的核心原则是：Folder 实例不跨请求复用。

5.5 程序结束时连接资源没释放

现象：本地测试多次后，邮件服务器上的连接数飙升，最终报 Too many connections。

原因：代码里创建了 Session 和 Store，但没有在 finally 块里调用 store.close() 和 folder.close()。连接一直挂在服务器上，直到超时被服务器回收。

解决：用 try-finally 包裹关键操作，这是最稳定的写法：

Store store = null; Folder folder = null; try { store = session.getStore("imap"); store.connect(hostname, username, password); folder = store.getFolder("inbox"); folder.open(Folder.READ_ONLY); // 读取邮件逻辑 } finally { if (folder != null && folder.isOpen()) { folder.close(false); } if (store != null) { store.close(); } }

注意 folder.close(false) 里的 false 指的是不 expunge，如果你在 READ_WRITE 模式下设置了删除标记，这里应该传 true 才能把删除操作真正提交。

6. 本地验证与打磨技巧：把课程设计改造得能放进真实项目

6.1 没有真实邮服时，用 devnull 把所有收发流程跑通

拿到源码包后第一件事不是直接连 QQ 邮箱或者公司邮服，因为很多公共 SMTP 服务器需要授权码，你还得去申请。最快的验证方式是用一个本地假邮件服务器。我一般推荐 GreenMail，它可以用 Maven 依赖直接拉起来，内存里跑一个完整的 SMTP 和 POP3/IMAP 服务：

# Maven 依赖 com.github.greenmail:greenmail:2.0.0

启动之后，JavaMail 程序把 host 指向 localhost，端口指向 GreenMail 监听的端口，账户密码随便设置，就能完整走一遍发送、接收、附件上传下载的流程。这个环境的优势是速度快、可重复、没有外网干扰，跑通之后再切换成真实邮服，最多改几个配置参数而已。

6.2 从课程设计到生产环境要改的三个地方

报告里的代码完成的是功能闭环，但距离生产可用还有一段距离。第一个要改的是 Session 的创建方式。报告里用 Session.getDefaultInstance(props)，这在单线程场景没问题，但并发场景下建议用 Session.getInstance(props)，它可以为每次请求创建独立的会话，避免共享 Session 的线程安全问题。

第二个要改的是发送方式。Transport.send(msg) 是同步阻塞的，在 Web 请求线程里直接调用会导致请求响应变慢。常见做法是把发送逻辑丢进线程池，或者用 Spring 的 @Async 注解异步处理，这样用户点发送按钮后立刻看到成功提示，邮件在后台慢慢发。

第三个要改的是附件大小限制。Tomcat 默认的 POST 请求大小上限是 2MB，附件稍大一点就会报 MaxUploadSizeExceededException。在 web.xml 里对发送邮件相关的 Servlet 或 JSP 配置更大的 max-post-size，或者从系统设计上绕过，先把附件传到一个临时文件服务器，邮件只保存链接。

6.3 验证邮件是否真正发送成功的判断标准

调试邮件系统时，最糟糕的情况是程序不报错，但邮件没收到。我的验证习惯是三步走：第一步看 Transport.send() 有没有抛异常，没抛只代，第二步检查发件服务器的已发送文件夹，第三是在收件端看原始邮件头和 Received 字段。

怎么直接看发件服务器日志，比如在 Properties 里设置 session.setDebug(true)，JavaMail 会把整个 SMTP 会话的详细交互过程打印到控制台，包括每次命令和响应码。看响应码是有规律可言的：250 代表邮件接受成功，550 代表收件人不存在或被拒绝，553 通常是发件人地址被服务器校验拦截。这套透排查经验，是我敲过很多次发送模块才真正把它们记在脑子里了。从那以后，我每接一个邮件系统的需求，都强制走一遍收件验证这个动作。希望帮到你。

本文还有配套的精品资源，点击获取