E-Commerce Order Support With an Agent Mailbox

利用代理邮箱实现电商订单支持

A helpdesk widget waits for customers to come to you; the support inbox is where they already went. Order status questions, return requests, shipping complaints, fraud alerts, marketing replies — for an online store it all piles into one address, and the e-commerce patterns overview opens with the honest diagnosis: manual triage of that pile doesn’t scale. 帮助台小部件（Widget）在等待客户主动联系，而支持收件箱则是客户早已习惯的沟通渠道。订单状态查询、退货请求、物流投诉、欺诈警报、营销回复——对于在线商店而言，所有这些信息都堆积在一个地址中。电商模式概览给出了一个诚实的诊断：手动分类处理这些堆积如山的信息是无法扩展的。

The architecture that does scale is an agent-owned mailbox per store. Agent Accounts — Nylas-hosted mailboxes currently in beta — are real addresses your application creates and controls entirely through the API. An AI layer answers the repetitive majority (“where’s my order?” has a database answer, not a human one) and escalates anything involving judgment, money, or anger. 能够实现扩展的架构是为每个商店配备一个由代理管理的邮箱。代理账户（Agent Accounts）——目前处于测试阶段的 Nylas 托管邮箱——是您的应用程序通过 API 完全创建和控制的真实地址。AI 层可以回答绝大多数重复性问题（“我的订单在哪里？”这类问题有数据库答案，无需人工介入），并将任何涉及判断、金钱或情绪化的问题升级处理。

A mailbox per store, by API

通过 API 为每个商店创建邮箱

Creating the account is one call against the Bring Your Own Auth endpoint with “provider”: “nylas”: 创建账户只需调用“自带认证”（Bring Your Own Auth）端点，并将 “provider” 设置为 “nylas”：

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": {
      "email": "support@orders.yourstore.com"
    }
  }'

The response carries a grant_id that works with every existing endpoint — Messages, Threads, Folders, Attachments, Webhooks — so nothing about your integration is agent-specific. The mailbox arrives with six system folders (inbox, sent, drafts, trash, junk, archive), and you can add custom ones like returns or fraud-review. For a multi-store platform, the per-customer pattern goes further: one account per merchant on each merchant’s own verified domain, each with its own send quota and sender reputation, all inside a single application. 响应中包含一个 grant_id，它适用于所有现有的端点——消息、会话、文件夹、附件、Webhooks——因此您的集成方案无需针对代理进行特殊处理。该邮箱自带六个系统文件夹（收件箱、已发送、草稿、垃圾桶、垃圾邮件、归档），您还可以添加自定义文件夹，如“退货”或“欺诈审查”。对于多商店平台，这种“每个客户一个邮箱”的模式可以进一步扩展：每个商户在其各自验证的域名下拥有一个账户，每个账户都有独立的发送配额和发件人信誉，所有这些都在同一个应用程序内管理。

Classify before you generate

先分类，后生成

Inbound mail fires the standard message.created webhook. From there, the e-commerce hub points at two agent recipes that split the problem sensibly: 入站邮件会触发标准的 message.created Webhook。由此，电商中心会指向两个代理方案，合理地分担任务：

An email triage agent classifies incoming mail into orders, inquiries, returns, and noise, then auto-drafts replies for just the top two categories. 邮件分类代理：将入站邮件分类为订单、咨询、退货和无效信息，并仅为前两类自动起草回复。
An email support agent generates knowledge-base-backed drafts behind confidence gates — it handles the order-status question without a human, and declines to guess when confidence is low. 邮件支持代理：在置信度门槛的控制下，生成基于知识库的草稿——它可以在无需人工干预的情况下处理订单状态查询，并在置信度较低时拒绝猜测。

That confidence gate is the load-bearing design decision. A wrong shipping estimate sent confidently costs you more trust than a slow correct one. Classification first, generation second, escalation as the default for everything ambiguous — returns disputes, chargebacks, and anything where the customer is already angry go straight to a person. 置信度门槛是整个设计的核心。自信地发送一个错误的物流预估，比缓慢但准确的回复更损害客户信任。先分类，后生成，并将所有模糊的情况默认升级处理——退货纠纷、拒付以及任何客户已经表现出愤怒的情况，都应直接转交给人工处理。

Spam never even has to reach the classifier: rules on the account can block known junk domains at the SMTP stage, which also keeps prompt-injection bait out of your LLM’s context window entirely. 垃圾邮件甚至无需到达分类器：账户规则可以在 SMTP 阶段拦截已知的垃圾邮件域名，这也完全避免了提示词注入（Prompt Injection）攻击进入您的 LLM 上下文窗口。

Pre-sort the pile before any code runs

在代码运行前预先整理邮件

Rules can do more than block junk. They match on sender fields (from.address, from.domain, from.tld) and run actions like assign_to_folder, mark_as_starred, or archive — inside the mail infrastructure, before your webhook handler fires. 规则的作用不仅限于拦截垃圾邮件。它们可以匹配发件人字段（地址、域名、顶级域名），并执行诸如 assign_to_folder（分配到文件夹）、mark_as_starred（加星标）或 archive（归档）等操作——这些都在邮件基础设施内部完成，在您的 Webhook 处理程序触发之前。

For a store, two rules earn their keep immediately: 对于商店而言，以下两条规则立竿见影：

# Returns from your logistics provider land pre-sorted
# 来自物流供应商的退货邮件会被预先分类
curl --request POST \
  --url "https://api.us.nylas.com/v3/rules" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Carrier notifications → shipping folder",
    "trigger": "inbound",
    "match": {
      "operator": "any",
      "conditions": [
        { "field": "from.domain", "operator": "is", "value": "ups.com" },
        { "field": "from.domain", "operator": "is", "value": "fedex.com" }
      ]
    },
    "actions": [
      { "type": "assign_to_folder", "value": "<SHIPPING_FOLDER_ID>" },
      { "type": "mark_as_read" }
    ]
  }'

A second rule can mark_as_starred mail from your highest-value customer domains so the escalation queue surfaces them first. Rules attach to workspaces rather than individual mailboxes — set the rule_ids once on a workspace and every store’s agent account in it inherits the same sorting, which is exactly what you want when store number forty-seven onboards. 第二条规则可以将来自高价值客户域名的邮件 mark_as_starred（加星标），以便在升级队列中优先处理。规则是绑定到工作区而非单个邮箱的——在工作区设置一次 rule_ids，该工作区内每个商店的代理账户都会继承相同的排序逻辑，这正是第 47 家商店入驻时您所需要的。

Customers attach things

客户发送的附件

Order support means attachments: photos of damaged goods, screenshots of error pages, PDFs of receipts. Inbound attachment limits come from your plan and the account’s policy — limit_attachment_size_limit, limit_attachment_count_limit, and limit_attachment_allowed_types are all tunable, so you can refuse executables while accepting images. 订单支持意味着附件：损坏商品的照片、错误页面的截图、收据的 PDF。入站附件限制取决于您的套餐和账户策略——limit_attachment_size_limit、limit_attachment_count_limit 和 limit_attachment_allowed_types 均可调整，因此您可以拒绝可执行文件，同时接受图片。

Attachment IDs arrive on the message object, and downloading is one call: 附件 ID 会随消息对象一起到达，下载只需一次调用：

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/attachments/<ATTACHMENT_ID>/download?message_id=<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

That’s the input for a vision model checking damage claims, or simply the file your human agent sees when the ticket escalates. 这是视觉模型检查损坏索赔的输入，或者仅仅是当工单升级时，人工客服所能看到的原始文件。

When a human takes over

当人工介入时

Escalation needs a place for the human to work, and here the mailbox model pays off twice. Because the Agent Account is a real mailbox, your support staff can connect to it over standard IMAP and SMTP from Outlook or Apple Mail and answer the angry-customer thread directly — same address, same thread, no context lost. 升级处理需要一个供人工操作的场所，而这正是邮箱模型发挥双重价值的地方。由于代理账户是一个真实的邮箱，您的支持人员可以通过 Outlook 或 Apple Mail 使用标准的 IMAP 和 SMTP 协议连接到该邮箱，并直接回复愤怒客户的会话——地址相同，会话相同，不会丢失任何上下文。

The API and the mail client see the same mailbox, so when the human is done, the agent’s view of the conversation includes everything the human wrote. API 和邮件客户端看到的是同一个邮箱，因此当人工处理完毕后，代理程序看到的对话记录中包含了人工回复的所有内容。

One implementation detail if your application also manages connected human grants: the message.created payload for an Agent Account is identical in shape to any other grant’s. Branch on the grant’s provider — “nylas” for Agent Accounts — to route agent-mailbox deliveries to the triage pipeline and leave human inboxes alone. 如果您的应用程序同时也管理人工连接的授权（Grants），这里有一个实现细节：代理账户的 message.created 有效载荷格式与其他授权完全相同。请根据授权的提供商进行分支判断——代理账户的提供商为 “nylas”——从而将代理邮箱的邮件路由到分类流水线，而忽略人工收件箱。

Replies come from the same address

回复来自同一地址

Outbound acknowledgments and answers go through the normal send endpoint on the same grant, so the customer sees one consistent identity and replies land back in the same mailbox — the full conversation is one thread your code can read. Outbound messages are capped at 40 MB total, which comfortably covers invoices and return labels as attachments. 外发确认和回复通过同一授权下的常规发送端点进行，因此客户看到的是统一的身份，回复也会落入同一个邮箱——完整的对话是一个您的代码可以读取的会话。外发消息总大小限制为 40 MB，这足以涵盖作为附件的发票和退货标签。