SuperAPI AI Directory

portaly-email-mcp

General & other

View repository

Updated 11-13 02:31

About this skill

Portaly Email MCP (Beta)

Use this skill when you are the one doing the work: the creator (a Portaly user, usually not an engineer) asks you, in conversation, to write and send a newsletter to the lists they collected on Portaly. You do it through Portaly's MCP tools — there is no code to write and no API key to manage.

This is not the skill for wiring an app's own email (receipts, sign-in codes) — that is portaly-email, with a pem_ key.

Reply to the creator in their language (usually Traditional Chinese), in plain words. Do not show them tool names, error codes, or JSON.

Beta — Portaly Email beta accounts, Premium Plus. Only accounts Portaly has invited to the Portaly Email beta (the same invite as the email API) can use it, and the account must be on Premium Plus (頂級+). Premium (頂級) members can start a 14-day Premium Plus trial in the Portaly admin. On top of that, the creator turns Email MCP on once by pressing 「開通發信 MCP」 at https://portaly.cc/admin/email/mcp — no invite needed for that step, only the profile's manager can press it. Until all of this holds the email tools do not appear at all, or every call answers email_mcp_not_enabled / email_mcp_activation_required / email_mcp_plan_required. Say this before setup if the creator has not mentioned being invited.

How approval works — read this first

Nothing reaches a mailing list until the creator approves that exact version in the Portaly admin.

  • You can draft, edit, and send test copies to the creator as often as needed.
  • submitForConfirmation returns a confirmUrl. Give it to the creator unchanged. They open it signed in to Portaly, look at the preview and recipient count, and press "確認上線".
  • Only the profile's manager can approve. You cannot, and Portaly staff cannot.
  • Any change after approval (subject, preview text, content, signature, lists, sending domain) cancels the approval — including the creator editing it in the admin. sendEmailCampaign then answers approval_required and sends nothing, until the creator confirms the new version.
  • Never tell the creator a newsletter was sent until sendEmailCampaign returned ok: true.

Workflow

1. Connect the Portaly MCP server

If the Portaly email tools (listMailingProjects, createEmailCampaign, …) are already available to you, skip to step 1.5.

The server is a remote MCP server with OAuth sign-in:

https://portaly.cc/mcp

Add it in whatever client you are running in:

  • Claude Code: claude mcp add --transport http portaly https://portaly.cc/mcp, then have the creator run /mcp and pick portaly to sign in.
  • Cursor: add to .cursor/mcp.json (or the global ~/.cursor/mcp.json):
    { "mcpServers": { "portaly": { "url": "https://portaly.cc/mcp" } } }
    
  • Claude (web / desktop), ChatGPT, and other chat apps: the creator adds a custom connector (remote MCP server) with the URL above in the app's settings. You cannot do this for them — walk them through it.

The creator signs in with their Portaly account in the browser and picks the profile to connect; one connection covers one profile. Most clients need a restart or a new session before the new tools show up.

If the client cannot do OAuth sign-in, the creator can create a token under "建立 token" at https://portaly.cc/admin/product/mcp and configure the same URL with the header Authorization: Bearer mcp_ptly_…. The token is shown once; it goes in the client's config, never in a chat message or a committed file.

Connected but no email tools? The server lists the email tools only for accounts that are in the Portaly Email beta, on Premium Plus, and have turned Email MCP on. Tell the creator to open 發信 MCP in the Portaly admin (https://portaly.cc/admin/email/mcp): if it shows "開通發信 MCP", they press it; otherwise it shows whether the account is enabled and offers the upgrade or trial. After turning it on or upgrading, the creator reconnects Portaly in their app (or refreshes the connector, or you start a new session) — most clients keep the tool list from when they first connected. Do not try to send email through other tools.

Every call answers HTTP 403 with "code": "plan_required"? That gate is in front of all Portaly MCP tools: the profile is below Premium (頂級). Tell the creator Email MCP needs Premium Plus (頂級+), or Premium with the 14-day Premium Plus trial, and stop.

1.5 Report the installed skill version

Right after installing or updating this skill, and once the email tools are available, call reportSkillVersion once with these arguments:

{"skillName": "portaly-email-mcp", "version": "0.1.1"}

version is this file's frontmatter version — use the literal value from the SKILL.md you are running. It only lets the creator's admin show "已安裝" or flag an update; ignore a failure and carry on.

2. Understand what to send

Ask what the newsletter is for (launch, monthly update, event, promotion), the key facts (dates, prices, links), and when it should go out. Do not invent facts — prices, dates, discount codes, and links come from the creator. If you write a placeholder like "[商品連結]", ask for it before submitting; submitForConfirmation lists any left in unfilledPlaceholders.

3. Pick the lists

Call listMailingProjects. It returns the creator's lists (id, name, subscriberCount) and sending domains. It never returns addresses, and you cannot add or import recipients — lists are collected or imported by the creator in the admin.

  • If it returns senderNote, the account has no sending address yet: the creator must press "立即開始" in the Portaly admin's email page first.
  • If there is more than one list, confirm with the creator which ones. Do not default to "all".
  • Leave domainId out to send from the Portaly domain; pass a custom domain's id only if the creator asks.

4. Draft

Call createEmailCampaign with subject, optional preheader (the preview text shown in the inbox), html, and listIds. It returns a draft; nothing is sent.

Content rules (enforced by Portaly):

  • Allowed tags: p, h2, h3, ul/ol/li, strong/b, em/i, u, br, a (https:// or mailto: only), img (https:// only). Other tags are removed and only their text is kept; styles are dropped except text alignment. Write simple, single-column content.
  • {{名稱}} inserts each recipient's name. Some recipients have no name; Portaly then drops the placeholder with its surrounding space and a following comma, so "嗨 {{名稱}}," reads "嗨". Still write sentences that read naturally without the name.
  • Subject and preview text: up to 200 characters each. Content: up to 900 KB.
  • Portaly appends the unsubscribe link to every email. Do not add your own.
  • Some wording is refused (banned_copy_terms): mainland-Chinese phrasing, AI filler, guarantee or exaggeration terms that carry legal risk in Taiwan, and unfilled 【請填】-style placeholders. Rewrite as the error message describes; if the text came from the creator, offer them your rewrite.

To revise, call updateEmailCampaign with only the fields that change. html replaces the whole body. Before rewriting html from getEmailCampaign, check htmlTruncated — if it is true, the returned html is incomplete and writing it back would cut the email.

5. Test copy

Call sendTestEmail. It sends one copy to the creator's own Portaly sign-in email (never anyone else), with "[試寄]" in front of the subject, and returns the masked address. Ask the creator to check layout and links on their phone. Limit: 20 test emails a day, and they use the email quota.

If it answers owner_email_unverified, skip the test copy — the confirmation page shows the same preview.

6. Get approval

Call submitForConfirmation. Give the creator the confirmUrl as-is and say what it is: "Please click this link to log in to Portaly. After checking the preview and the number of recipients, press 'Confirm to go live.' Only after you press it can I send it out." Also tell them the " recipientCount.

Then wait for the creator to tell you they approved. To check, call listEmailCampaigns or getEmailCampaign: reviewStatus is approved once they did; pendingReview with approvalOutdated: true means it changed after approval and needs confirming again.

7. Send

Confirm the timing with the creator, then call sendEmailCampaign. There is no scheduling parameter: it starts sending now, so if the creator wants a later time, wait and call it then (or have them schedule it in the admin). A send cannot be recalled.

  • Recipients are fixed at this moment; anyone who unsubscribed after the approval does not get it.
  • Before sending a large list, previewAudience tells you if today's sending limit spreads it over several days (multiDay with firstDay and finishDay). Tell the creator — it continues automatically.

8. Results

getEmailCampaign returns cumulative stats (delivered, opened, clicked, bounced, complained, failed) and unsubscribedCount. Opens and clicks keep arriving for days; say "so far". Summarise in plain words (e.g. "目前送達 980 封,開信 410 人(約 42%),點擊 63 人").

Guardrails

These are what the tools enforce; quote them as limits, with what to do instead.

  • Only drafts can be edited or sent through these tools (campaign_not_draft otherwise). Scheduled, sending, or sent campaigns are changed in the Portaly admin; for a new version, create a new draft.
  • A paused send is resumed only by the creator pressing "繼續寄送" in the admin.
  • send_quota_insufficient: not enough email quota for the whole list; nothing was sent. Tell the creator — do not retry, and do not split the list to squeeze it through.
  • Rate limits per connection: 120 reads and 20 writes a minute. Do not loop on writes.
  • email_mcp_not_enabled / email_mcp_plan_required: the account cannot use Email MCP right now. Say so plainly, point to the 發信 MCP page in the admin, and stop — never work around it with other tools.
  • email_mcp_activation_required: Email MCP is off for this account (you only see this if it was turned off after you got the tools). Give the creator https://portaly.cc/admin/email/mcp, ask them to press "開通發信 MCP" and reconnect, then continue — never work around it with other tools.

Errors

A failed call returns { "ok": false, "error": { "code", "message" } }. The message (in Chinese) says what to tell the creator and what to do next; follow it.

Code Meaning What to do
approval_required Not approved, or changed after approval submitForConfirmation and hand over the link again
campaign_not_draft Scheduled, sending, or sent Change it in the admin, or draft a new one
sender_not_set_up No sending address yet Creator sets it up in the admin's email page
send_quota_insufficient Not enough quota for the whole list Tell the creator; nothing was sent
owner_email_unverified No verified sign-in email for test copies Skip the test copy; use the confirmation preview
email_mcp_not_enabled Account not invited to the Portaly Email beta Tell the creator; stop
email_mcp_activation_required Email MCP not turned on for this account Creator presses "開通發信 MCP" at https://portaly.cc/admin/email/mcp, reconnects; then continue
email_mcp_plan_required Needs Premium Plus Tell the creator about upgrading or the 14-day trial; stop
banned_copy_terms The new text uses wording Portaly refuses Rewrite those words and call again
invalid_arguments A parameter is missing or wrong Fix the named parameter

Full reference: https://portaly.ai/docs#tag/email (Email section, "Email MCP").