Skip to content

k.mail ​

发信、收信(IMAP)、邮件解析、Amazon SES 与反垃圾检测

概述 ​

k.mail 提供站点脚本中的邮件能力,主要子 API:

成员用途
smtp发送邮件(站点默认通道或指定 SMTP 服务器)
imap从 IMAP 收件箱拉取邮件
utility解析原始邮件、下载附件
amazonses通过 AWS SES 发信
spamassassinSpamAssassin 垃圾邮件检测
moduleKooboo Mail 模块上下文(邮箱应用)
createMessage() / createSmtpServer()构造邮件与 SMTP 配置对象

createMessage() / createSmtpServer() ​

方法参数返回值说明
createMessage()无MailMessage创建邮件消息对象。
createSmtpServer()无SmtpServer创建外部 SMTP 服务器配置对象。
ts
const msg = k.mail.createMessage()
msg.from = "sender@example.com"
msg.to = "user@example.com"
msg.subject = "Hello"
msg.htmlBody = "<p>HTML body</p>"
msg.textBody = "Plain text"

const server = k.mail.createSmtpServer()
server.host = "smtp.example.com"
server.port = 465
server.ssl = true
server.username = "sender@example.com"
server.password = "your-password"

MailMessage 常用字段 ​

字段说明
from / to / cc / bcc / replyTo单个字符串;多个地址用英文逗号分隔(见下)
subject主题
htmlBody / textBody / body正文
replyTo回复地址
attachments附件集合
方法说明
addAttachment(urlOrPath)按 URL 或路径添加附件
addAttachment(filename, bytes)二进制附件
attachObject(filename, obj)附加对象
toEml()导出 EML 字符串

多个收件人 ​

to、cc、bcc、from、replyTo 在服务端会解析为多个邮箱。同一字段可写在一个字符串里,用英文逗号分隔多个地址,也支持带显示名的 RFC 5322 写法:

ts
msg.to = "alice@example.com,bob@example.com"
msg.to = "Alice <alice@example.com>, Bob <bob@example.com>"
msg.cc = "carol@example.com; dave@example.com" // 「; 」会被规范为逗号

使用站点默认通道 k.mail.smtp.send(msg) 时,组织邮件额度按解析出的收件人个数扣减(to 中每个有效地址计一次)。外部 SMTP 的 k.mail.smtp.send(server, msg) 由 MailKit 按 MIME 中的 To/Cc/Bcc 一并投递。

smtp.send() ​

方法参数返回值说明
smtp.send(message)`message: MailMessageobject`void
smtp.send(server, message)server: SmtpServer, `message: MailMessageobject`void

使用站点默认发信通道 ​

传入 MailMessage 或等价 plain 对象(须含 from、to):

ts
k.api.post(() => {
    k.mail.smtp.send({
        from: "noreply@your-domain.com",
        to: k.request.form.email,
        subject: "Notification",
        htmlBody: "<p>Thanks for signing up.</p>"
    })
    return { sent: true }
})

发信受组织邮件额度限制;失败时可能抛出 No enough email sending credits 等异常。

使用外部 SMTP 服务器 ​

ts
k.api.post(() => {
    const msg = k.mail.createMessage()
    msg.from = "sender@qq.com"
    msg.to = k.request.form.to
    msg.subject = "Test"
    msg.htmlBody = "<div>Content</div>"

    const server = k.mail.createSmtpServer()
    server.host = "smtp.qq.com"
    server.port = 465
    server.ssl = true
    server.username = "sender@qq.com"
    server.password = k.request.form.smtpPassword

    k.mail.smtp.send(server, msg)
    return { sent: true }
})

imap ​

从 IMAP 收件箱拉取邮件(须配置 ImapSetting)。

ts
const setting = {
    emailAddress: "user@example.com",
    host: "imap.example.com",
    forceSSL: true,
    port: 993,
    password: "your-password"
}
方法说明
collect(setting, start, count)按 UID 区间拉取
collectLatestMails(setting, count)最近若干封
get(setting, uid)按 UID 取单封
getRange(setting)当前邮箱 UID 范围
ts
k.api.post(() => {
    const setting = {
        emailAddress: k.request.form.email,
        host: k.request.form.host,
        forceSSL: true,
        port: 993,
        password: k.request.form.password
    }

    const list = k.mail.imap.collectLatestMails(setting, 5)
    const first = list[0]
    const detail = first ? k.mail.utility.parseDetail(first.rawBody) : null

    return {
        count: list.length,
        subject: detail?.subject
    }
})

返回项含 uID、rawBody(原始 RFC822 文本)。

utility ​

方法说明
parseSummary(rawBody)解析为邮件摘要对象
parseDetail(rawBody)解析为详情(含 HTML、附件列表等)
downloadAttachment(rawBody, fileName)从原始邮件取出附件二进制
ts
k.api.post(() => {
    const raw = k.request.body.raw
    const detail = k.mail.utility.parseDetail(raw)
    return {
        subject: detail.subject,
        from: detail.from,
        attachmentCount: detail.attachments?.length ?? 0
    }
})

amazonses ​

ts
const client = k.mail.amazonses.createEmail({
    accessKeyId: "...",
    secretAccessKey: "...",
    region: "EUCentral1"
})

const res = client.send({
    from: "me@example.com",
    to: ["user@example.com"],
    subject: "Subject",
    htmlBody: "<p>HTML</p>",
    textBody: "Text"
})

也可 createEmail 后对 MailMessage 调用 sendRaw(msg) 发送完整 MIME(含复杂附件)。

spamassassin ​

通过 SpamAssassin 服务检测垃圾邮件。

入口说明
spamassassin.local本地默认 SpamAssassin
spamassassin.connect(host, user, port)远程实例
方法说明
check(mail)是否垃圾邮件及分数
report(mail)含详细报告正文
ping()服务健康检查
ts
k.api.post(() => {
    const raw = k.request.body.raw
    const rsp = k.mail.spamassassin.local.check(raw)
    return {
        spam: rsp.spam,
        score: rsp.score,
        currentScore: rsp.currentScore,
        criticalScore: rsp.criticalScore
    }
})

module ​

k.mail.module 仅在 Kooboo Mail 模块执行上下文中可用(类似 k.module),提供 list()、config、baseUrl、localSqlite 等。在普通站点 API 中访问会抛错。

相关文档 ​