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.

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.

A mailbox per store, by API

Creating the account is one call against the Bring Your Own Auth endpoint with "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": "[e-mail]"
    }
  }'

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.

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:

• 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.

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. 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.

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. Attachment IDs arrive on the message object, and downloading is one call:

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. 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.

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.

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. For batch sends like shipping-delay notices, the hub also points to a mail-merge pattern with per-recipient scheduling.

The numbers that shape your rollout

Free-plan limits from the docs, worth knowing before launch day:

• 200 messages per account per day send rate — paid plans drop the daily cap by default, and a policy can set a stricter quota per account if a merchant's agent misbehaves.
• 3 GB of storage per organization, with more on paid plans.
• Retention of 30 days for inbox and 7 days for spam, configurable through policy retention limits — so if order history must outlive that window, sync what matters into your own database.
• Unlimited domains per application, which is what makes the mailbox-per-merchant model practical.

For a store doing modest volume, 200 sends a day covers a lot of acknowledgments; for peak season, plan the upgrade before Black Friday does it for you.

Where to start

Provision one agent mailbox on a trial domain, point your message.created webhook at a classifier with exactly two auto-answer categories — order status and shipping ETA — and route everything else to your existing human queue untouched. Run it for two weeks and measure what fraction of mail never needed a person. If you run a store today, what percentage of your support volume do you suspect is answerable straight from your orders table?