@matimo/mailchimp 0.1.0-alpha.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tallclub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# @matimo/mailchimp — Mailchimp Tools for Matimo
+
+Mailchimp email marketing integration tools for Matimo's universal AI tools ecosystem. Manage audiences, subscribers, and campaigns through YAML-defined tools that work with any AI framework.
+
+## 📦 Installation
+
+```bash
+npm install @matimo/mailchimp
+# or
+pnpm add @matimo/mailchimp
+```
+
+## 🛠️ Available Tools (7 Total)
+
+| Category | Tool | Method | Description |
+|----------|------|--------|-------------|
+| **Audiences** | `mailchimp-get-lists` | GET | Get all audiences/lists |
+| **Subscribers** | `mailchimp-add-list-member` | POST | Subscribe a contact to an audience |
+| **Subscribers** | `mailchimp-get-list-members` | GET | Get subscribers with filters and pagination |
+| **Subscribers** | `mailchimp-update-list-member` | PATCH | Update subscriber info or status |
+| **Subscribers** | `mailchimp-remove-list-member` | DELETE | Remove subscriber (🔒 requires approval) |
+| **Campaigns** | `mailchimp-create-campaign` | POST | Create an email campaign |
+| **Campaigns** | `mailchimp-send-campaign` | POST | Send a campaign (🔒 requires approval) |
+
+## 🚀 Quick Start
+
+```typescript
+import { MatimoInstance } from 'matimo';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// Get all audiences
+const audiences = await matimo.execute('mailchimp-get-lists', {
+  server_prefix: 'us6',
+  count: 10,
+});
+
+// Add a subscriber
+await matimo.execute('mailchimp-add-list-member', {
+  server_prefix: 'us6',
+  list_id: 'your_list_id',
+  email_address: 'jane@example.com',
+  status: 'subscribed',
+  merge_fields: { FNAME: 'Jane', LNAME: 'Doe' },
+});
+```
+
+## 🔐 Authentication
+
+Mailchimp Marketing API v3 uses **API key authentication**.
+
+### Step 1: Get Your API Key
+
+1. Log in to your Mailchimp account
+2. Navigate to **Account → Extras → API Keys**
+3. Click **Create A Key**
+4. Copy the generated key (format: `abc123def456-us6`)
+
+### Step 2: Find Your Server Prefix
+
+Your server prefix is the suffix on your API key after the dash.
+
+```
+API Key: abc123def456-us6
+              ↑
+         server_prefix = "us6"
+```
+
+### Step 3: Set Environment Variables
+
+```bash
+export MAILCHIMP_API_KEY="abc123def456-us6"
+```
+
+### Step 4: Use in Tool Calls
+
+Pass `server_prefix` as a parameter to every tool call:
+
+```typescript
+await matimo.execute('mailchimp-get-lists', {
+  server_prefix: 'us6',   // ← your data center prefix
+});
+```
+
+## 📚 Integration Examples
+
+### Factory Pattern
+
+```typescript
+import 'dotenv/config';
+import { MatimoInstance } from 'matimo';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+const SERVER = process.env.MAILCHIMP_SERVER_PREFIX || 'us6';
+
+// List audiences
+const result = await matimo.execute('mailchimp-get-lists', {
+  server_prefix: SERVER,
+  count: 10,
+});
+console.info('Audiences:', result.data.lists.map(l => l.name));
+
+// Add subscriber
+await matimo.execute('mailchimp-add-list-member', {
+  server_prefix: SERVER,
+  list_id: 'abc123def4',
+  email_address: 'newuser@example.com',
+  status: 'subscribed',
+  merge_fields: { FNAME: 'New', LNAME: 'User' },
+});
+```
+
+### Decorator Pattern
+
+```typescript
+import { MatimoInstance, tool, setGlobalMatimoInstance } from 'matimo';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+setGlobalMatimoInstance(matimo);
+
+class MailchimpAgent {
+  @tool('mailchimp-get-lists')
+  async getLists(server_prefix: string, count?: number): Promise<unknown> {
+    return undefined;
+  }
+
+  @tool('mailchimp-add-list-member')
+  async addSubscriber(
+    server_prefix: string,
+    list_id: string,
+    email_address: string,
+    status: string
+  ): Promise<unknown> {
+    return undefined;
+  }
+}
+
+const agent = new MailchimpAgent();
+const lists = await agent.getLists('us6', 10);
+```
+
+### With LangChain
+
+```typescript
+import { MatimoInstance, convertToolsToLangChain } from 'matimo';
+import { ChatOpenAI } from '@langchain/openai';
+import { createAgent } from 'langchain';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// Filter and convert Mailchimp tools for LangChain
+const mailchimpTools = matimo
+  .listTools()
+  .filter(t => t.name.startsWith('mailchimp-'));
+
+const langchainTools = convertToolsToLangChain(mailchimpTools, matimo);
+
+const llm = new ChatOpenAI({ model: 'gpt-4o-mini' });
+const agent = await createAgent({ llm, tools: langchainTools });
+
+// Agent can now use Mailchimp tools autonomously
+await agent.invoke({
+  input: 'Subscribe john@example.com to the main newsletter list'
+});
+```
+
+## 🔧 API Reference
+
+### mailchimp-get-lists
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `server_prefix` | string | ✅ Yes | Data center prefix (e.g., `us6`) |
+| `count` | number | No | Results per page (default: 10, max: 1000) |
+| `offset` | number | No | Records to skip for pagination (default: 0) |
+
+### mailchimp-add-list-member
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `server_prefix` | string | ✅ Yes | Data center prefix |
+| `list_id` | string | ✅ Yes | Audience/list ID |
+| `email_address` | string | ✅ Yes | Subscriber email address |
+| `status` | string | ✅ Yes | `subscribed`, `unsubscribed`, `pending`, or `cleaned` |
+| `merge_fields` | object | No | Merge fields like `{"FNAME": "Jane", "LNAME": "Doe"}` |
+| `tags` | array | No | Array of tag name strings |
+
+### mailchimp-get-list-members
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `server_prefix` | string | ✅ Yes | Data center prefix |
+| `list_id` | string | ✅ Yes | Audience/list ID |
+| `status` | string | No | Filter by status: `subscribed`, `unsubscribed`, `pending`, `cleaned` |
+| `count` | number | No | Results per page (default: 10, max: 1000) |
+| `offset` | number | No | Records to skip |
+
+### mailchimp-update-list-member
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `server_prefix` | string | ✅ Yes | Data center prefix |
+| `list_id` | string | ✅ Yes | Audience/list ID |
+| `subscriber_hash` | string | ✅ Yes | MD5 hash of the lowercase email address |
+| `status` | string | No | New subscription status |
+| `email_address` | string | No | New email address |
+| `merge_fields` | object | No | Merge fields to update |
+
+### mailchimp-remove-list-member ⚠️ Requires Approval
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `server_prefix` | string | ✅ Yes | Data center prefix |
+| `list_id` | string | ✅ Yes | Audience/list ID |
+| `subscriber_hash` | string | ✅ Yes | MD5 hash of the lowercase email address |
+
+### mailchimp-create-campaign
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `server_prefix` | string | ✅ Yes | Data center prefix |
+| `type` | string | ✅ Yes | `regular`, `plaintext`, `rss`, or `variate` |
+| `list_id` | string | No | Audience/list ID to send to |
+| `subject_line` | string | No | Campaign subject line |
+| `preview_text` | string | No | Preview text for email clients |
+| `title` | string | No | Internal campaign title |
+| `from_name` | string | No | Sender display name |
+| `reply_to` | string | No | Reply-to email address |
+
+### mailchimp-send-campaign ⚠️ Requires Approval
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `server_prefix` | string | ✅ Yes | Data center prefix |
+| `campaign_id` | string | ✅ Yes | Campaign ID from `mailchimp-create-campaign` |
+
+## 💡 Tips
+
+### Finding the Subscriber Hash
+
+The `subscriber_hash` is the MD5 hash of the lowercase email address:
+
+```javascript
+import { createHash } from 'crypto';
+const email = 'jane@example.com';
+const hash = createHash('md5').update(email.toLowerCase()).digest('hex');
+// Use hash as subscriber_hash
+```
+
+### Rate Limits
+
+- Mailchimp Marketing API: 10 requests per second per account
+- Some batch operations count as multiple requests
+- Implement appropriate delays in high-volume scenarios
+
+### Pagination
+
+For large audiences, paginate through results:
+
+```typescript
+let offset = 0;
+const count = 100;
+let allMembers = [];
+
+while (true) {
+  const result = await matimo.execute('mailchimp-get-list-members', {
+    server_prefix: 'us6',
+    list_id: 'abc123',
+    count,
+    offset,
+  });
+  allMembers.push(...result.data.members);
+  if (result.data.members.length < count) break;
+  offset += count;
+}
+```
+
+## 🐛 Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `404 Resource Not Found` | Wrong `list_id` or `subscriber_hash` | Verify IDs from Mailchimp dashboard |
+| `400 Invalid Resource` | Malformed request body | Check parameter types and required fields |
+| `401 Unauthorized` | Invalid or expired API key | Regenerate API key at Mailchimp account settings |
+| `403 Forbidden` | Insufficient permissions | Check API key permissions |
+| `429 Too Many Requests` | Rate limit exceeded | Implement delays between requests |
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines on contributing to Matimo.
+
+---
+
+Part of the [Matimo](https://github.com/tallclub/matimo) ecosystem — Write YAML once, use everywhere.

package/assets/mc-logo.svg

@@ -0,0 +1,15 @@
+<svg width="38" height="40" viewBox="0 0 38 40" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0)">
+<path d="M35.4564 23.7461C35.7634 23.9117 36.0345 24.1365 36.2539 24.4075C36.595 24.8245 37 25.5651 37 26.7228C37 28.3318 36.3816 30.045 36.1932 30.5305C36.1885 30.5398 36.1807 30.5491 36.1807 30.56C35.0954 33.1717 33.1998 35.3665 30.7727 36.8215C28.4004 38.2453 25.5204 39 22.4457 39H21.874C18.989 38.9399 16.1728 38.1087 13.7183 36.5928C11.5573 35.2377 9.80917 33.317 8.66388 31.0393C7.34228 30.8341 6.10864 30.2504 5.11251 29.3588C3.83683 28.2291 3.04712 26.7509 2.89136 25.1948C2.80667 24.4079 2.85245 23.6125 3.02687 22.8405L2.48482 22.3815C1.61255 21.6455 1.10321 20.5858 1.01443 19.341C0.941223 18.3047 1.14683 17.1221 1.62502 15.815C2.74183 12.7714 5.30566 9.14581 8.48631 6.11775C9.90595 4.74017 11.4809 3.53186 13.1794 2.51708C14.9302 1.50721 16.5189 0.995269 17.9021 1.00149C18.9853 0.973166 20.0403 1.3487 20.8616 2.05493C20.9071 2.08828 21.5749 2.74181 22.1033 3.2589L22.145 3.29976L22.3771 3.20173C24.131 2.47506 25.8568 2.09228 27.3693 2.09228C30.5561 2.09228 32.6215 3.80392 32.6215 6.44919C32.6215 8.08148 31.8225 9.91138 30.3443 11.6853C30.7474 12.3092 31.0516 12.9915 31.2462 13.7081C31.4562 14.4388 31.5709 15.1935 31.5873 15.9535C31.6029 16.2803 31.6169 16.8015 31.6293 17.2683C32.6044 17.5578 33.8287 18.0464 34.5639 18.8244C35.1335 19.3887 35.5069 20.1206 35.6293 20.9126C35.7507 21.6931 35.6295 22.492 35.282 23.2015C35.3131 23.2902 35.3505 23.4007 35.3785 23.4894C35.4066 23.5781 35.433 23.6637 35.4564 23.7461Z" fill="#001D28"/>
+<path d="M8.446 20.7569C8.16153 20.7416 7.87628 20.762 7.59683 20.8174C5.57352 21.2268 4.43041 22.9461 4.6574 25.1942C4.85989 27.2229 6.9077 28.934 8.802 28.9848C8.99665 28.9901 9.19135 28.9764 9.38336 28.9438C11.4312 28.5934 11.9701 26.3617 11.632 24.1676C11.2499 21.6918 9.57932 20.8191 8.446 20.7569ZM10.4514 26.6237C10.3683 26.7584 10.2494 26.8672 10.1081 26.9378C9.96668 27.0084 9.80843 27.038 9.65117 27.0232C9.21352 26.9888 8.72525 26.6695 8.6583 25.877C8.65371 25.4926 8.72416 25.111 8.86569 24.7537C8.95434 24.5298 8.96344 24.2821 8.89148 24.0522C8.81952 23.8223 8.67087 23.6243 8.4705 23.4913C8.35128 23.4129 8.21769 23.359 8.07751 23.3329C7.93733 23.3067 7.79336 23.3088 7.65399 23.339C7.51755 23.3679 7.38822 23.4238 7.27354 23.5034C7.15887 23.5829 7.06115 23.6846 6.98608 23.8024C6.88071 23.9835 6.79842 24.1771 6.74113 24.3788C6.73133 24.4148 6.72153 24.4426 6.715 24.4607C6.62192 24.7112 6.47331 24.7881 6.3737 24.7701C6.32634 24.7701 6.26102 24.7325 6.21856 24.6178C6.10915 24.3002 6.2055 23.4144 6.79012 22.7594C6.98319 22.5527 7.22241 22.3949 7.48813 22.299C7.75385 22.2031 8.03848 22.1718 8.31863 22.2076C8.61521 22.248 8.89714 22.3616 9.13913 22.5382C9.38111 22.7148 9.57557 22.9489 9.70506 23.2195C10.1068 23.9858 9.74915 24.7898 9.54176 25.2712L9.4797 25.4136C9.3458 25.7329 9.33926 26.0113 9.46011 26.1979C9.511 26.2713 9.57929 26.3308 9.65882 26.3711C9.73835 26.4114 9.82664 26.4312 9.91572 26.4288C9.9996 26.4283 10.0831 26.4167 10.1639 26.3944C10.2685 26.3699 10.3779 26.3437 10.4448 26.4272C10.467 26.4548 10.4796 26.4889 10.4808 26.5243C10.4819 26.5597 10.4716 26.5946 10.4514 26.6237Z" fill="#EFEEEA"/>
+<path d="M36.9567 24.6372C36.7266 24.352 36.4424 24.1155 36.1206 23.9413C36.0961 23.8545 36.0683 23.7644 36.0389 23.6711C36.0095 23.5778 35.9703 23.4615 35.9377 23.3682C36.302 22.6216 36.4292 21.7809 36.3018 20.9596C36.1736 20.1262 35.782 19.356 35.1849 18.7622C34.4141 17.9435 33.1305 17.4293 32.1082 17.1248C32.0952 16.6336 32.0805 16.085 32.0642 15.7412C32.0469 14.9414 31.9267 14.1473 31.7065 13.3784C31.5025 12.6243 31.1836 11.9063 30.761 11.2498C32.3107 9.38317 33.1485 7.45759 33.1485 5.73996C33.1485 2.95638 30.9831 1.15525 27.6419 1.15525C26.0563 1.15525 24.2469 1.55805 22.4081 2.32271L22.1648 2.42587C21.6047 1.8757 20.8682 1.15197 20.8192 1.11595C19.9582 0.37279 18.8521 -0.0223774 17.7164 0.00743079C16.2663 0.0008812 14.6006 0.539585 12.7651 1.60226C10.9843 2.6701 9.33319 3.94159 7.84482 5.3912C4.51019 8.57757 1.82224 12.3927 0.651367 15.5955C0.15003 16.9709 -0.0655288 18.2153 0.0112231 19.3058C0.104305 20.6157 0.638303 21.7308 1.55279 22.5053L2.12109 22.9883C1.93823 23.8007 1.89023 24.6377 1.97901 25.4657C2.14231 27.1031 2.97026 28.6586 4.3077 29.8474C5.35205 30.7856 6.64541 31.3999 8.03099 31.6158C9.23173 34.0126 11.0645 36.0337 13.3301 37.4596C15.9034 39.0548 18.856 39.9295 21.8806 39.9927C22.0799 39.9927 22.2807 39.9927 22.48 39.9927C25.7035 39.9927 28.723 39.1986 31.2101 37.7003C33.7547 36.1692 35.7421 33.8596 36.8799 31.1115C36.8799 31.1 36.8881 31.0902 36.893 31.0803C37.0906 30.5695 37.7389 28.7667 37.7389 27.0736C37.7389 25.8554 37.3143 25.076 36.9567 24.6372ZM35.6699 30.6088C33.462 35.9123 28.1939 38.8645 21.9198 38.6779C16.0703 38.5027 11.0815 35.4031 8.89812 30.3632C7.57701 30.3632 6.2167 29.7819 5.18137 28.8633C4.09214 27.894 3.4275 26.6414 3.2887 25.3331C3.18324 24.3913 3.29958 23.4379 3.62836 22.5495L2.4036 21.5081C-3.20746 16.7597 14.341 -2.80234 19.9553 2.10658L21.8692 3.98795C21.8692 3.98795 22.9062 3.54585 22.9127 3.54257C27.8346 1.49255 31.8306 2.4799 31.8421 5.7416C31.8421 7.43794 30.7659 9.41428 29.0398 11.2089C29.6652 11.7918 30.1666 12.7022 30.454 13.7419C30.6444 14.4085 30.7476 15.0971 30.761 15.7903C30.7904 16.4813 30.8231 18.0827 30.8263 18.1203L31.5204 18.3135C32.8415 18.6852 33.7821 19.1797 34.241 19.6644C34.6542 20.0673 34.9248 20.5946 35.0118 21.1659C35.0901 21.6096 35.0787 22.3923 34.4957 23.2667C34.6067 23.5288 34.7021 23.7972 34.7815 24.0706C34.9268 24.5373 35.0313 24.9254 35.0477 24.9827C35.5817 24.9827 36.421 25.6 36.421 27.0867C36.421 28.5735 35.8136 30.2371 35.6699 30.6088Z" fill="#EFEEEA"/>
+<path d="M34.7814 26.1871C34.5928 26.0813 34.3747 26.041 34.1609 26.0725C34.0471 25.3765 33.848 24.6973 33.5681 24.0503C32.2731 25.0753 30.6042 25.7974 29.3353 26.1625C27.4962 26.6805 25.5839 26.888 23.6769 26.7766C22.4489 26.6767 21.6372 26.3164 21.3319 27.312C24.1358 28.3419 27.1046 27.9014 27.1046 27.9014C27.1182 27.8999 27.1321 27.901 27.1453 27.9049C27.1585 27.9088 27.1707 27.9152 27.1814 27.9239C27.192 27.9326 27.2009 27.9434 27.2073 27.9556C27.2137 27.9677 27.2177 27.9811 27.2189 27.9948C27.2213 28.0177 27.2164 28.0408 27.205 28.0608C27.1936 28.0808 27.1762 28.0966 27.1552 28.1061C27.1552 28.1061 24.869 29.1688 21.2519 28.0455C21.3531 28.897 22.181 29.2785 22.5762 29.4324C22.9147 29.5589 23.264 29.6542 23.6197 29.7173C28.1073 30.4918 32.3041 27.9162 33.2545 27.2711C33.3248 27.2219 33.3721 27.2711 33.315 27.3546C33.2872 27.4006 33.2566 27.4449 33.2235 27.4872C32.0673 28.9821 28.9581 30.7145 24.9147 30.7129C23.1511 30.7129 21.389 30.0907 20.7407 29.1328C19.7364 27.6477 20.6917 25.4797 22.3639 25.7057L23.0972 25.7876C25.1891 26.0217 28.2167 25.7286 30.7119 24.5661C32.9982 23.5034 33.8571 22.3343 33.7281 21.3879C33.6846 21.0941 33.5464 20.8227 33.3346 20.615C32.9247 20.2122 32.2731 19.8978 31.1757 19.59C30.8132 19.4869 30.5666 19.4263 30.3021 19.3346C29.8317 19.1708 29.5982 19.0529 29.546 18.1655C29.5231 17.7774 29.4545 16.4233 29.43 15.8633C29.3876 14.8809 29.2667 13.5447 28.4404 12.9913C28.227 12.854 27.9802 12.7782 27.7268 12.7719C27.5856 12.7636 27.444 12.7774 27.3071 12.8128C26.8335 12.8931 26.5543 13.1403 26.2048 13.4383C25.1711 14.3012 24.2974 14.4437 23.3258 14.4011C22.7461 14.3765 22.1321 14.2865 21.4266 14.2374L21.0151 14.2144C19.382 14.1309 17.6445 15.5391 17.3538 17.5384C16.9505 20.3219 18.9607 21.7612 19.5421 22.6045C19.6325 22.7117 19.6893 22.8432 19.7054 22.9827C19.69 23.1377 19.6158 23.2807 19.498 23.3822C17.8388 25.0933 17.3081 27.8114 17.9336 30.0759C18.0098 30.3562 18.1081 30.6299 18.2275 30.8946C19.6972 34.3331 24.2452 35.9329 28.6919 34.4756C29.2711 34.2822 29.8331 34.0406 30.3723 33.7535C31.3449 33.2703 32.2214 32.6133 32.959 31.8148C34.1033 30.6657 34.857 29.184 35.1129 27.5805C35.2501 26.6898 35.0541 26.3508 34.7814 26.1871ZM28.7948 20.4955C28.7948 20.8623 28.5678 21.1505 28.3049 21.1505C28.0419 21.1505 27.828 20.8443 27.8329 20.4775C27.8378 20.1107 28.0615 19.8225 28.3228 19.8225C28.5841 19.8225 28.8078 20.1304 28.8013 20.4955H28.7948ZM27.5798 16.1646C28.0991 16.0811 28.349 16.6181 28.5351 17.5089C28.6592 18.1065 28.6347 18.6551 28.4976 18.9744C28.2412 18.9408 27.9815 18.9408 27.7251 18.9744C27.477 18.6176 27.3098 18.2108 27.2352 17.7823C27.0425 16.8932 27.0621 16.2481 27.5798 16.1646ZM25.8406 20.9458C25.9582 20.7051 26.3191 20.6412 26.6474 20.8033C26.9756 20.9654 27.1471 21.2945 27.0295 21.5303C26.9119 21.7661 26.5494 21.8333 26.2228 21.6711C25.8962 21.509 25.7231 21.1848 25.8406 20.9458ZM23.8092 20.6756C23.7553 20.7591 23.6459 20.7444 23.3976 20.7165C22.874 20.6372 22.3388 20.6936 21.843 20.8803C21.73 20.9277 21.6115 20.9607 21.4903 20.9785C21.461 20.9782 21.4328 20.9678 21.4103 20.9491C21.3981 20.9379 21.3886 20.9242 21.3824 20.9089C21.3762 20.8936 21.3734 20.8771 21.3743 20.8606C21.4019 20.7118 21.4863 20.5796 21.6095 20.4922C21.8717 20.2764 22.1914 20.1426 22.5289 20.1074C23.1951 20.0272 23.6818 20.3383 23.7961 20.5233C23.8133 20.5445 23.8237 20.5703 23.826 20.5975C23.8283 20.6246 23.8225 20.6518 23.8092 20.6756ZM20.0989 19.7587C20.0124 19.7456 19.9748 19.7079 19.9634 19.6588C19.9307 19.5065 20.1659 19.2527 20.4141 19.071C20.7761 18.8054 21.2001 18.6377 21.6454 18.5841C22.0908 18.5305 22.5423 18.5927 22.9567 18.7648C23.3438 18.9253 23.6766 19.1942 23.9153 19.5393C24.0035 19.6833 24.0198 19.7963 23.9627 19.8553C23.8745 19.9502 23.6459 19.8422 23.2752 19.6784C22.8298 19.4588 22.3374 19.3525 21.8414 19.369C21.0183 19.4197 20.3031 19.7816 20.0989 19.7587Z" fill="#EFEEEA"/>
+<path d="M25.7473 9.65984C25.8191 9.67622 25.8649 9.55341 25.8012 9.51739C24.7469 8.96866 23.5836 8.66321 22.3963 8.62337C22.3848 8.62329 22.3735 8.62 22.3638 8.61386C22.354 8.60772 22.3461 8.59898 22.3411 8.58861C22.336 8.57824 22.3339 8.56666 22.335 8.55515C22.3361 8.54365 22.3404 8.53269 22.3473 8.52349C22.5326 8.28205 22.7483 8.06575 22.9891 7.87999C22.9998 7.8713 23.0074 7.85946 23.011 7.84616C23.0146 7.83286 23.0139 7.81876 23.009 7.80589C23.0041 7.79301 22.9953 7.78201 22.9838 7.77444C22.9723 7.76687 22.9588 7.76313 22.945 7.76374C21.49 7.85379 19.8292 8.55296 18.8739 9.20628C18.8635 9.21332 18.8511 9.21701 18.8386 9.21686C18.826 9.21671 18.8138 9.21273 18.8035 9.20545C18.7932 9.19817 18.7854 9.18793 18.781 9.17609C18.7767 9.16425 18.7761 9.15137 18.7792 9.13915C18.8772 8.77135 19.0215 8.41756 19.2087 8.0863C19.215 8.07498 19.2174 8.06193 19.2158 8.04909C19.2141 8.03624 19.2084 8.02427 19.1994 8.01493C19.1905 8.00558 19.1788 7.99936 19.166 7.99718C19.1533 7.995 19.1402 7.99697 19.1287 8.0028C17.5936 8.79038 15.8822 10.1904 14.4909 11.8032C14.4812 11.8151 14.4762 11.83 14.4766 11.8453C14.477 11.8606 14.4829 11.8753 14.4932 11.8866C14.5035 11.8979 14.5175 11.9051 14.5327 11.9069C14.5478 11.9088 14.5631 11.9051 14.5758 11.8965C15.7761 11.0189 17.4238 10.2051 19.581 9.67785C21.609 9.2073 23.7166 9.20114 25.7473 9.65984Z" fill="#EFEEEA"/>
+<path d="M20.5548 4.67148C20.5548 4.67148 19.0263 2.8949 18.5658 2.76391C15.7276 1.99597 9.5989 6.23355 5.68618 11.8335C4.10379 14.098 1.83715 18.1112 2.91985 20.1744C3.05375 20.4298 3.80984 21.0864 4.21483 21.427C4.94219 20.4084 6.03506 19.7123 7.26368 19.485C8.86731 15.1607 11.5438 11.185 15.0875 8.44895C16.8025 7.04018 18.6312 5.77667 20.5548 4.67148Z" fill="#EFEEEA"/>
+</g>
+<defs>
+<clipPath id="clip0">
+<rect width="38" height="40" fill="white"/>
+</clipPath>
+</defs>
+</svg>

package/definition.yaml

@@ -0,0 +1,50 @@
+# Mailchimp Provider Definition
+#
+# This file defines provider metadata for Mailchimp.
+# Mailchimp Marketing API v3 accepts API key auth via the Authorization header.
+#
+# Setup:
+# 1. Log in to Mailchimp → Account → Extras → API Keys
+# 2. Generate a new API key
+# 3. Note your server prefix (last part of the API key, e.g. "us6" from "abc123-us6")
+# 4. Set MAILCHIMP_API_KEY environment variable to your full API key
+# 5. Pass server_prefix as a parameter to each tool call
+
+name: mailchimp-provider
+type: provider
+version: '1.0.0'
+tags:
+  - Email Marketing
+  - Audiences
+  - Campaigns
+  - Marketing Automation
+
+description: |
+  Mailchimp Marketing API v3 Provider Configuration
+
+  All Mailchimp tools use API key authentication via the Authorization header.
+  Format: Authorization: apikey YOUR_API_KEY
+
+  Authentication:
+  - API Key found at: https://us1.admin.mailchimp.com/account/api/
+  - Set MAILCHIMP_API_KEY environment variable to your full API key
+  - Server prefix is the datacenter suffix on your API key (e.g. "us6" from "abc123-us6")
+
+provider:
+  name: mailchimp
+  displayName: Mailchimp
+
+  # Mailchimp uses API key auth via Authorization header (apikey <key>)
+  authType: api_key
+
+  # Additional metadata
+  documentation: https://mailchimp.com/developer/marketing/api/
+  learnMore: https://mailchimp.com/developer/marketing/guides/quick-start/
+
+  # UI assets and branding
+  assets:
+    icon: assets/mc-logo.svg
+    logo: assets/mc-logo.svg
+  brand_color: '#FFE01B'
+  homepage: 'https://mailchimp.com'
+  alt: 'Mailchimp'

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@matimo/mailchimp",
+  "version": "0.1.0-alpha.11",
+  "description": "Mailchimp email marketing tools for Matimo — manage audiences, subscribers, and campaigns",
+  "type": "module",
+  "files": [
+    "tools",
+    "README.md",
+    "definition.yaml",
+    "assets"
+  ],
+  "peerDependencies": {
+    "matimo": "0.1.0-alpha.11"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@matimo/core": "0.1.0-alpha.11"
+  }
+}

package/tools/mailchimp-add-list-member/definition.yaml

@@ -0,0 +1,117 @@
+name: mailchimp-add-list-member
+version: '1.0.0'
+description: >
+  Add a new subscriber to a Mailchimp audience (list). Use this to subscribe
+  a contact to receive email campaigns. Supports setting merge fields (first name, last name)
+  and tags for segmentation.
+
+parameters:
+  server_prefix:
+    type: string
+    required: true
+    description: >
+      Your Mailchimp data center prefix (e.g. "us6"). Found at the end of your API key:
+      "abc123-us6" → server_prefix is "us6".
+  list_id:
+    type: string
+    required: true
+    description: The unique ID of the Mailchimp audience/list to add the member to
+  email_address:
+    type: string
+    required: true
+    description: The email address of the subscriber to add
+  status:
+    type: string
+    required: true
+    description: >
+      Subscriber status: "subscribed" (opted in), "unsubscribed" (opted out),
+      "pending" (requires email confirmation), or "cleaned" (invalid email)
+    enum:
+      - subscribed
+      - unsubscribed
+      - pending
+      - cleaned
+  merge_fields:
+    type: object
+    required: false
+    description: >
+      Key-value pairs for merge fields such as FNAME (first name) and LNAME (last name).
+      Example: {"FNAME": "Jane", "LNAME": "Doe"}
+  tags:
+    type: array
+    required: false
+    description: Array of tag names to apply to the subscriber for segmentation
+
+execution:
+  type: http
+  method: POST
+  url: 'https://{server_prefix}.api.mailchimp.com/3.0/lists/{list_id}/members'
+  headers:
+    Authorization: 'apikey {MAILCHIMP_API_KEY}'
+    Content-Type: application/json
+  body:
+    email_address: '{email_address}'
+    status: '{status}'
+    merge_fields: '{merge_fields}'
+    tags: '{tags}'
+  timeout: 30000
+
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+  notes:
+    env: MAILCHIMP_API_KEY
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    data:
+      type: object
+      properties:
+        id:
+          type: string
+          description: MD5 hash of the subscriber email (subscriber_hash)
+        email_address:
+          type: string
+        status:
+          type: string
+        merge_fields:
+          type: object
+        tags:
+          type: array
+        list_id:
+          type: string
+        timestamp_opt:
+          type: string
+        timestamp_signup:
+          type: string
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: 'Subscribe a new contact'
+    params:
+      server_prefix: us6
+      list_id: abc123def4
+      email_address: jane@example.com
+      status: subscribed
+      merge_fields:
+        FNAME: Jane
+        LNAME: Doe
+    expected_result: 'Returns the new member record with id (subscriber_hash) and status'
+  - name: 'Add pending subscriber with tags'
+    params:
+      server_prefix: us6
+      list_id: abc123def4
+      email_address: pending@example.com
+      status: pending
+      tags:
+        - newsletter
+        - vip
+    expected_result: 'Returns member record with pending status awaiting confirmation'

package/tools/mailchimp-create-campaign/definition.yaml

@@ -0,0 +1,125 @@
+name: mailchimp-create-campaign
+version: '1.0.0'
+description: >
+  Create a new Mailchimp email campaign. Supports regular, plaintext, RSS,
+  and A/B test variate campaign types. After creating, configure the campaign
+  content and use mailchimp-send-campaign to send it.
+
+parameters:
+  server_prefix:
+    type: string
+    required: true
+    description: >
+      Your Mailchimp data center prefix (e.g. "us6"). Found at the end of your API key:
+      "abc123-us6" → server_prefix is "us6".
+  type:
+    type: string
+    required: true
+    description: >
+      Campaign type: "regular" (standard email), "plaintext" (text-only email),
+      "rss" (RSS-driven campaign), or "variate" (A/B test campaign)
+    enum:
+      - regular
+      - plaintext
+      - rss
+      - variate
+  list_id:
+    type: string
+    required: false
+    description: >
+      The unique ID of the Mailchimp audience/list to send this campaign to.
+      Required when type is "regular" or "plaintext".
+  subject_line:
+    type: string
+    required: false
+    description: The subject line for the campaign email
+  preview_text:
+    type: string
+    required: false
+    description: Preview text displayed after the subject line in email clients (max 150 chars)
+  title:
+    type: string
+    required: false
+    description: Internal title for the campaign (used to identify it in Mailchimp dashboard)
+  from_name:
+    type: string
+    required: false
+    description: The "From" name subscribers will see in their inbox
+  reply_to:
+    type: string
+    required: false
+    description: The reply-to email address for the campaign
+
+execution:
+  type: http
+  method: POST
+  url: 'https://{server_prefix}.api.mailchimp.com/3.0/campaigns'
+  headers:
+    Authorization: 'apikey {MAILCHIMP_API_KEY}'
+    Content-Type: application/json
+  body:
+    type: '{type}'
+    recipients:
+      list_id: '{list_id}'
+    settings:
+      subject_line: '{subject_line}'
+      preview_text: '{preview_text}'
+      title: '{title}'
+      from_name: '{from_name}'
+      reply_to: '{reply_to}'
+  timeout: 30000
+
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+  notes:
+    env: MAILCHIMP_API_KEY
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    data:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Unique campaign ID (use this with mailchimp-send-campaign)
+        type:
+          type: string
+        status:
+          type: string
+          description: Campaign status (save, paused, schedule, sending, sent)
+        settings:
+          type: object
+        recipients:
+          type: object
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: 'Create a regular campaign'
+    params:
+      server_prefix: us6
+      type: regular
+      list_id: abc123def4
+      subject_line: 'Welcome to our newsletter!'
+      preview_text: 'Check out what we have for you this month'
+      title: 'Monthly Newsletter - March 2026'
+      from_name: 'Acme Marketing'
+      reply_to: marketing@acme.com
+    expected_result: 'Returns campaign record with id for use in mailchimp-send-campaign'
+  - name: 'Create a plaintext campaign'
+    params:
+      server_prefix: us6
+      type: plaintext
+      list_id: abc123def4
+      subject_line: 'Quick update from us'
+      from_name: 'Acme Team'
+      reply_to: hello@acme.com
+    expected_result: 'Returns plaintext campaign record ready to add content and send'

package/tools/mailchimp-get-list-members/definition.yaml

@@ -0,0 +1,101 @@
+name: mailchimp-get-list-members
+version: '1.0.0'
+description: >
+  Get all members (subscribers) from a Mailchimp audience/list with optional
+  filtering by subscription status and pagination support.
+
+parameters:
+  server_prefix:
+    type: string
+    required: true
+    description: >
+      Your Mailchimp data center prefix (e.g. "us6"). Found at the end of your API key:
+      "abc123-us6" → server_prefix is "us6".
+  list_id:
+    type: string
+    required: true
+    description: The unique ID of the Mailchimp audience/list to get members from
+  status:
+    type: string
+    required: false
+    description: >
+      Filter members by subscription status. Options: "subscribed", "unsubscribed",
+      "pending", "cleaned", "transactional", "archived". Omit to get all members.
+    enum:
+      - subscribed
+      - unsubscribed
+      - pending
+      - cleaned
+      - transactional
+      - archived
+  count:
+    type: number
+    required: false
+    description: Number of members to return per page (default 10, max 1000)
+    default: 10
+    min: 1
+    max: 1000
+  offset:
+    type: number
+    required: false
+    description: Number of records to skip for pagination (default 0)
+    default: 0
+    min: 0
+
+execution:
+  type: http
+  method: GET
+  url: 'https://{server_prefix}.api.mailchimp.com/3.0/lists/{list_id}/members'
+  headers:
+    Authorization: 'apikey {MAILCHIMP_API_KEY}'
+    Content-Type: application/json
+  query_params:
+    status: '{status}'
+    count: '{count}'
+    offset: '{offset}'
+  timeout: 30000
+
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+  notes:
+    env: MAILCHIMP_API_KEY
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    data:
+      type: object
+      properties:
+        members:
+          type: array
+          description: Array of member objects with email, status, and merge fields
+        list_id:
+          type: string
+        total_items:
+          type: number
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: 'Get all subscribed members'
+    params:
+      server_prefix: us6
+      list_id: abc123def4
+      status: subscribed
+      count: 100
+      offset: 0
+    expected_result: 'Returns array of subscribed members with total_items count'
+  - name: 'Get first page of all members'
+    params:
+      server_prefix: us6
+      list_id: abc123def4
+      count: 10
+      offset: 0
+    expected_result: 'Returns first 10 members across all statuses'

package/tools/mailchimp-get-lists/definition.yaml

@@ -0,0 +1,81 @@
+name: mailchimp-get-lists
+version: '1.0.0'
+description: >
+  Get all Mailchimp audiences (lists) for the authenticated account.
+  Returns a paginated list of all audiences with subscriber counts and settings.
+
+parameters:
+  server_prefix:
+    type: string
+    required: true
+    description: >
+      Your Mailchimp data center prefix (e.g. "us6"). Found at the end of your API key:
+      "abc123-us6" → server_prefix is "us6".
+  count:
+    type: number
+    required: false
+    description: Number of audiences to return (default 10, max 1000)
+    default: 10
+    min: 1
+    max: 1000
+  offset:
+    type: number
+    required: false
+    description: Number of records to skip for pagination (default 0)
+    default: 0
+    min: 0
+
+execution:
+  type: http
+  method: GET
+  url: 'https://{server_prefix}.api.mailchimp.com/3.0/lists'
+  headers:
+    Authorization: 'apikey {MAILCHIMP_API_KEY}'
+    Content-Type: application/json
+  query_params:
+    count: '{count}'
+    offset: '{offset}'
+  timeout: 30000
+
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+  notes:
+    env: MAILCHIMP_API_KEY
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    data:
+      type: object
+      properties:
+        lists:
+          type: array
+          description: Array of audience objects
+        total_items:
+          type: number
+          description: Total number of audiences in the account
+        _links:
+          type: array
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: 'Get first 10 audiences'
+    params:
+      server_prefix: us6
+      count: 10
+      offset: 0
+    expected_result: 'Returns a list of audiences with total_items count'
+  - name: 'Get next page of audiences'
+    params:
+      server_prefix: us6
+      count: 10
+      offset: 10
+    expected_result: 'Returns the second page of audiences'

package/tools/mailchimp-remove-list-member/definition.yaml

@@ -0,0 +1,64 @@
+name: mailchimp-remove-list-member
+version: '1.0.0'
+description: >
+  Archive (unsubscribe and remove) a subscriber from a Mailchimp audience/list.
+  This action archives the contact so they no longer appear as an active member.
+  Use the MD5 hash of the lowercase email address as the subscriber_hash.
+  ⚠️ This action requires approval — it cannot be undone from this tool.
+
+requires_approval: true
+
+parameters:
+  server_prefix:
+    type: string
+    required: true
+    description: >
+      Your Mailchimp data center prefix (e.g. "us6"). Found at the end of your API key:
+      "abc123-us6" → server_prefix is "us6".
+  list_id:
+    type: string
+    required: true
+    description: The unique ID of the Mailchimp audience/list the member belongs to
+  subscriber_hash:
+    type: string
+    required: true
+    description: >
+      The MD5 hash of the subscriber's lowercase email address. You can generate this
+      using MD5("email@example.com"). Use the id field from list member responses.
+
+execution:
+  type: http
+  method: DELETE
+  url: 'https://{server_prefix}.api.mailchimp.com/3.0/lists/{list_id}/members/{subscriber_hash}'
+  headers:
+    Authorization: 'apikey {MAILCHIMP_API_KEY}'
+    Content-Type: application/json
+  timeout: 30000
+
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+  notes:
+    env: MAILCHIMP_API_KEY
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    statusCode:
+      type: number
+
+error_handling:
+  retry: 1
+  backoff_type: linear
+  initial_delay_ms: 1000
+
+examples:
+  - name: 'Remove a subscriber'
+    params:
+      server_prefix: us6
+      list_id: abc123def4
+      subscriber_hash: b775e3e869bc8eae5fcb23cdc5ec64ff
+    expected_result: 'Returns 204 No Content on success (success: true, statusCode: 204)'

package/tools/mailchimp-send-campaign/definition.yaml

@@ -0,0 +1,59 @@
+name: mailchimp-send-campaign
+version: '1.0.0'
+description: >
+  Send a Mailchimp campaign. This triggers the campaign to be delivered
+  to all recipients in the audience. The campaign must have content set
+  and all required settings configured before sending.
+  ⚠️ This action requires approval as it triggers mass email delivery.
+
+requires_approval: true
+
+parameters:
+  server_prefix:
+    type: string
+    required: true
+    description: >
+      Your Mailchimp data center prefix (e.g. "us6"). Found at the end of your API key:
+      "abc123-us6" → server_prefix is "us6".
+  campaign_id:
+    type: string
+    required: true
+    description: >
+      The unique ID of the campaign to send. Obtained from mailchimp-create-campaign
+      response or from the Mailchimp dashboard.
+
+execution:
+  type: http
+  method: POST
+  url: 'https://{server_prefix}.api.mailchimp.com/3.0/campaigns/{campaign_id}/actions/send'
+  headers:
+    Authorization: 'apikey {MAILCHIMP_API_KEY}'
+    Content-Type: application/json
+  timeout: 30000
+
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+  notes:
+    env: MAILCHIMP_API_KEY
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    statusCode:
+      type: number
+
+error_handling:
+  retry: 1
+  backoff_type: linear
+  initial_delay_ms: 2000
+
+examples:
+  - name: 'Send a prepared campaign'
+    params:
+      server_prefix: us6
+      campaign_id: a1b2c3d4e5
+    expected_result: 'Returns 204 No Content on success (success: true, statusCode: 204)'

package/tools/mailchimp-update-list-member/definition.yaml

@@ -0,0 +1,105 @@
+name: mailchimp-update-list-member
+version: '1.0.0'
+description: >
+  Update an existing subscriber's information in a Mailchimp audience/list.
+  Use the subscriber_hash (MD5 hash of the lowercase email address) to identify the member.
+  Supports updating status, email address, and merge fields.
+
+parameters:
+  server_prefix:
+    type: string
+    required: true
+    description: >
+      Your Mailchimp data center prefix (e.g. "us6"). Found at the end of your API key:
+      "abc123-us6" → server_prefix is "us6".
+  list_id:
+    type: string
+    required: true
+    description: The unique ID of the Mailchimp audience/list the member belongs to
+  subscriber_hash:
+    type: string
+    required: true
+    description: >
+      The MD5 hash of the subscriber's lowercase email address. You can generate this
+      using MD5("email@example.com"). Use the id field from mailchimp-add-list-member response.
+  status:
+    type: string
+    required: false
+    description: >
+      Update subscription status. Options: "subscribed", "unsubscribed", "pending", "cleaned"
+    enum:
+      - subscribed
+      - unsubscribed
+      - pending
+      - cleaned
+  email_address:
+    type: string
+    required: false
+    description: New email address for the subscriber (updates the email)
+  merge_fields:
+    type: object
+    required: false
+    description: >
+      Key-value pairs for merge fields to update. Example: {"FNAME": "Jane", "LNAME": "Smith"}
+
+execution:
+  type: http
+  method: PATCH
+  url: 'https://{server_prefix}.api.mailchimp.com/3.0/lists/{list_id}/members/{subscriber_hash}'
+  headers:
+    Authorization: 'apikey {MAILCHIMP_API_KEY}'
+    Content-Type: application/json
+  body:
+    status: '{status}'
+    email_address: '{email_address}'
+    merge_fields: '{merge_fields}'
+  timeout: 30000
+
+authentication:
+  type: api_key
+  location: header
+  name: Authorization
+  notes:
+    env: MAILCHIMP_API_KEY
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    data:
+      type: object
+      properties:
+        id:
+          type: string
+        email_address:
+          type: string
+        status:
+          type: string
+        merge_fields:
+          type: object
+        list_id:
+          type: string
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 500
+
+examples:
+  - name: 'Unsubscribe a member'
+    params:
+      server_prefix: us6
+      list_id: abc123def4
+      subscriber_hash: b775e3e869bc8eae5fcb23cdc5ec64ff
+      status: unsubscribed
+    expected_result: 'Returns updated member record with unsubscribed status'
+  - name: 'Update subscriber name'
+    params:
+      server_prefix: us6
+      list_id: abc123def4
+      subscriber_hash: b775e3e869bc8eae5fcb23cdc5ec64ff
+      merge_fields:
+        FNAME: Jane
+        LNAME: Smith
+    expected_result: 'Returns updated member record with new merge fields'