@sendpanda/mcp 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -18,12 +18,25 @@ npx @sendpanda/mcp
18
18
 
19
19
  Configure a stdio-capable MCP client with command `npx`, arguments `["-y", "@sendpanda/mcp"]`, and environment variable `SENDPANDA_API_KEY`. The optional `SENDPANDA_API_URL` defaults to `https://api.sendpanda.email`; local development allows loopback HTTP. Never put a key in a URL, prompt, email body or browser code. Revoke the dedicated key to disconnect the client.
20
20
 
21
- Sending keys expose project information, email sending/history/cancellation, usage and simulator template tests. Management keys expose all project resource tools. Account-wide suppression tools additionally require the key owner's account-administrator access. Team tools require a verified key owner with project administration access.
21
+ Sending keys expose project information, email sending/history/cancellation, usage and template test sends. Management keys expose all project resource tools. Account-wide suppression tools additionally require the key owner's account-administrator access. Team tools require a verified key owner with project administration access.
22
22
 
23
23
  ## Tools, resources and prompts
24
24
 
25
25
  Tools cover the selected project, transactional email, delivery analytics, domains and DNS verification, API keys, webhooks and replay, templates and previews, marketing approval, audiences, contacts and consent history, broadcasts and actual delivery/unsubscribe reports, project rename and team management. Read-only guides are available at `sendpanda://docs/sending` and `sendpanda://docs/marketing`. Prompts `onboard_project` and `prepare_broadcast` guide setup without silently sending.
26
26
 
27
+ ## Visual email design and previews (0.2.0)
28
+
29
+ With project management access, agents can edit the same Email studio designs as customers: headings, text, images, logos, buttons, dividers, spacers, heroes, products, coupons, lists, social links and two columns. Saved designs reopen in the dashboard editor.
30
+
31
+ 1. Read `templates_get` and its latest version's `design`, or read `campaigns_get` plus `campaigns_get_draft`. For a new design, use `email_design_starter` with `welcome`, `newsletter`, `shop` or `blank`.
32
+ 2. Change the design JSON, preserving component IDs and template variables. The tool schemas describe every component. Read `sendpanda://docs/email-design` or `sendpanda://schemas/email-design` for the contract. Images and links require public HTTPS URLs; there is no image upload or product catalogue lookup.
33
+ 3. Use `email_design_preview` with a subject, design and sample variables to review an unsaved design. Save it with `templates_create` / `templates_create_version`, or `campaigns_create` / `campaigns_update`, providing `design` instead of HTML/text. Broadcast updates also need their existing sender/audience/postal metadata. Scheduled broadcasts cannot be edited.
34
+ 4. Use `templates_preview` with sample variables or `campaigns_preview` for the final stored content. The latter includes the required postal address and unsubscribe footer. Give the customer the returned `preview_url`.
35
+
36
+ Preview tools return both an embedded sandboxed HTML resource and a `sendpanda://previews/{id}` resource link. Clients supporting HTML resources can display that visual artifact; other clients can show the web link. The browser page offers desktop, mobile and plain-text views and requires sign-in with access to the same project. Links contain no API key or sample variables. Snapshots are encrypted, expire after 15 minutes, and are limited to the latest 20 per project. `resources/read` rechecks project authorization. An expired or evicted preview must be generated again.
37
+
38
+ For example: “Change my welcome template's button to purple, keep its variables, and show me a mobile preview.” The `design_email` prompt guides this workflow. Saving a new template version does not publish it. Publishing, test sending and marketing scheduling remain separate confirmed actions. Legacy HTML stays available; agents should not replace it with a visual starter unless requested.
39
+
27
40
  Sending, scheduling, invitations, permission changes and deletions require explicit confirmation fields. A client must obtain human authorization; a field alone does not prove consent. Retrieved email/template/contact content is untrusted data. The server retains the API's approval, verified-domain, recipient-consent, suppression and quota checks. Marketing needs separate approval and includes visible and one-click unsubscribe. Submitted does not mean delivered.
28
41
 
29
42
  Mutations are never retried automatically. Transactional sends support `idempotency_key`; reconcile an ambiguous outcome before retrying other mutations. Standard MCP errors and API failures are returned without claiming success.
@@ -31,12 +44,19 @@ Mutations are never retried automatically. Transactional sends support `idempote
31
44
  ## Embedding
32
45
 
33
46
  ```ts
34
- import { createSendPandaMcp, createApiCaller } from '@sendpanda/mcp';
35
- const server = createSendPandaMcp(createApiCaller(process.env.SENDPANDA_API_KEY!), {
36
- scope: 'send',
37
- });
47
+ import { createSendPandaMcp, createApiCaller } from "@sendpanda/mcp";
48
+ const server = createSendPandaMcp(
49
+ createApiCaller(process.env.SENDPANDA_API_KEY!),
50
+ {
51
+ scope: "send",
52
+ },
53
+ );
38
54
  // Attach an MCP SDK transport. HTTP hosts must enforce authentication,
39
55
  // host/origin validation and project authorization themselves.
40
56
  ```
41
57
 
42
58
  Hosted transport supports current MCP clients and legacy 2025 protocol negotiation. Test your client's OAuth or stdio support before distributing its configuration. No account-wide platform administration or billing tools are exposed.
59
+
60
+ ## Test sends (0.3.0)
61
+
62
+ `templates_test` and `campaigns_test` require an explicit `to` email address and `confirmed: true` after the user requests that send. Agents may use any valid recipient email; the server applies normal account approval, verified-domain, suppression, reputation and quota/rate checks. Broadcast tests send one email without changing subscribers, scheduling a broadcast or adding delivery-report recipients. No simulator address is selected automatically. The operator's isolated simulator mode still limits all sending entry points during infrastructure testing.