用途:Portaly Email MCP(Beta)用于协助 Portaly 创作者在对话中撰写并寄送电子报给其在 Portaly 收集的名单。工具通过 Portaly 的 MCP 工具操作,无需写代码,也无需管理 API Key。此技能不用于应用自身的寄信需求(如收据、登入验证码),那属于 portaly-email(使用 pem_ 金钥)。与创作者沟通时,应使用对方语言(通常为繁体中文)、用平实说法,不显示工具名称、错误代码或 JSON。
使用条件:仅受邀参加 Portaly Email Beta(与 Email API 同一邀请)且订阅 Premium Plus(顶级+)的账号可用;Premium(顶级)会员可在后台开始 14 天 Premium Plus 试用。此外,创作者须在 https://portaly.cc/admin/email/mcp 按下「開通發信 MCP」一次(此步骤无需邀请,仅档案管理员可操作)。若条件不符,邮件工具不会出现,或每次呼叫回传 email_mcp_not_enabled / email_mcp_activation_required / email_mcp_plan_required。若创作者未提及受邀,应在设定前先说明。
连接方式:Portaly MCP 为远程 MCP 服务器,网址 https://portaly.cc/mcp,采 OAuth 登入。Claude Code 可执行 claude mcp add --transport http portaly https://portaly.cc/mcp,再让创作者执行 /mcp 选择 portaly 登入;Cursor 可在 .cursor/mcp.json(或全局 ~/.cursor/mcp.json)加入 {"mcpServers": {"portaly": {"url": "https://portaly.cc/mcp"}}};Claude(网页/桌面)、ChatGPT 及其他聊天应用则由创作者在设定中新增自订连接器(远程 MCP 服务器)并填入上述网址,此步骤须由创作者完成。创作者在浏览器以 Portaly 账号登入并选择要连接的档案,一个连接对应一个档案;多数客户端需重新启动或开新会话才会出现新工具。若客户端不支持 OAuth 登入,创作者可在 https://portaly.cc/admin/product/mcp 的「建立 token」建立 token,以同一网址搭配 Authorization: Bearer mcp_ptly_… 标头设定;token 只显示一次,应放入客户端设定,不可出现在对话或提交的文件中。连接后若无邮件工具,通常是账号条件未满足或工具清单未更新,应请创作者到后台「發信 MCP」页面开通或升级,之后重新连接或开新会话。若所有呼叫都回传 HTTP 403 与 plan_required,表示档案未达 Premium,应告知 Email MCP 需要 Premium Plus 或 Premium 加 14 天试用,并停止。
安装后回报:安装或更新此技能且邮件工具可用后,呼叫 reportSkillVersion 一次,参数为 {"skillName": "portaly-email-mcp", "version": "0.1.1"},version 使用所执行 SKILL.md 的 frontmatter 版本字面值;失败可忽略。
工作流程:先询问电子报目的(发布、月报、活动、促销)、关键事实(日期、价格、连结)与寄送时间,不可自行编造价格、日期、折扣码或连结;若写了「[商品連結]」等占位符,须在提交前补齐,submitForConfirmation 会在 unfilledPlaceholders 列出未填项。接着呼叫 listMailingProjects 取得清单(id、name、subscriberCount)与寄送网域;它不会回传地址,也不能新增或汇入收件人。若有多个清单,须与创作者确认要寄哪些,不可预设全部。留空 domainId 表示从 Portaly 网域寄送,仅在创作者要求时传入自订网域 id。若回传 senderNote,表示尚无寄送地址,创作者须先在 Portaly 后台邮件页面按「立即開始」。
草稿:呼叫 createEmailCampaign,参数为 subject、选填 preheader(收件匣预览文字)、html、listIds,会回传草稿且不会寄出。内容规则由 Portaly 强制:允许标签为 p、h2、h3、ul/ol/li、strong/b、em/i、u、br、a(仅 https:// 或 mailto:)、img(仅 https://);其他标签会被移除只留文字,样式除文字对齐外会被丢弃,应写简单单栏内容。{{名稱}} 会插入收件人姓名;部分收件人无姓名时,Portaly 会连同前后空白与后接逗号一并移除,因此仍要写出没有姓名也通顺的句子。主旨与预览文字各上限 200 字元,内容上限 900 KB。Portaly 会自动附加取消订阅连结,勿自行新增。部分措辞会被拒绝(banned_copy_terms),包括中国大陆用语、AI 填充语、在台湾有法律风险的保证或夸大用语,以及未填的【請填】式占位符;应依错误讯息改写,若原文来自创作者,可提供改写建议。修改时呼叫 updateEmailCampaign,只传要变更的栏位;html 会替换整个内容。从 getEmailCampaign 取回 html 重写前,须检查 htmlTruncated,若为 true 表示回传内容不完整,写回会截断邮件。
测试与确认:呼叫 sendTestEmail 会寄一份到创作者自己的 Portaly 登入信箱(不会寄给别人),主旨前加「[試寄]」,并回传去识别化地址;可请创作者在手机检查版面与连结。限制为每天 20 封测试信,且会使用邮件额度。若回传 owner_email_unverified,可跳过测试信,确认页面会显示相同预览。确认时呼叫 submitForConfirmation,取得 confirmUrl 后原样交给创作者,并说明:「請點這個連結登入 Portaly,看過預覽和收件人數後按『確認上線』,按了我才能寄出。」同时告知 recipientCount。只有档案管理员能核准,AI 与 Portaly 人员都不能。核准后若有任何变更(主旨、预览文字、内容、签名、清单、寄送网域),包括创作者在后台自行编辑,都会取消核准;此时 sendEmailCampaign 会回传 approval_required 且不寄出。在 sendEmailCampaign 回传 ok: true 前,绝不可告诉创作者电子报已寄出。
寄送与结果:与创作者确认时间后呼叫 sendEmailCampaign;没有排程参数,呼叫即开始寄送,若要点稍后寄送,应等到该时间再呼叫,或请创作者在后台排程。寄送无法收回;收件人在此刻固定,核准后取消订阅者不会收到。寄送大名单前,可用 previewAudience 得知当日寄送上限是否会将名单分散到多天(multiDay 含 firstDay 与 finishDay),并告知创作者会自继续。getEmailCampaign 回传累计统计(delivered、opened、clicked、bounced、complained、failed)与 unsubscribedCount;开信与点击会持续数天,应说「目前」。用平实说法摘要,例如「目前送達 980 封,開信 410 人(約 42%),點擊 63 人」。
限制与错误:只有草稿能通过这些工具编辑或寄送(否则 campaign_not_draft);已排程、寄送中或已寄送的活动须在 Portaly 后台调整,新版本则建立新草稿。暂停的寄送只能由创作者在后台按「繼續寄送」恢复。send_quota_insufficient 表示额度不足以寄给整个名单,此时未寄出任何邮件,应告知创作者,不要重试,也不要拆分名单规避。每个连接的限制为每分钟 120 次读取与 20 次写入,勿对写入进行循环。email_mcp_not_enabled / email_mcp_plan_required 表示账号目前无法使用 Email MCP,应据实告知并指向后台「發信 MCP」页面后停止,绝不用其他工具绕过。email_mcp_activation_required 表示 Email MCP 已关闭,应请创作者到 https://portaly.cc/admin/email/mcp 按「開通發信 MCP」并重新连接后继续。错误回传格式为 { "ok": false, "error": { "code", "message" } },message 会以中文说明应告知创作者的内容与后续动作,应依其指示处理。