@rawdash/connector-mailchimp 0.0.1
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 +131 -0
- package/dist/index.d.ts +601 -0
- package/dist/index.js +652 -0
- package/dist/index.js.map +1 -0
- package/package.json +43 -0
package/README.md
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
<!-- This file is generated from connector metadata by scripts/generate-connector-docs.ts. Do not edit by hand. -->
|
|
2
|
+
|
|
3
|
+
# @rawdash/connector-mailchimp
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@rawdash/connector-mailchimp)
|
|
6
|
+
[](https://github.com/rawdash/rawdash/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
Sync Mailchimp campaigns, audiences (lists), automations, and per-campaign engagement stats for marketing email analytics.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm install @rawdash/connector-mailchimp
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Authentication
|
|
17
|
+
|
|
18
|
+
A Mailchimp Marketing API key. The data-center suffix after the dash (e.g. `-us1`) selects the API host the connector talks to.
|
|
19
|
+
|
|
20
|
+
1. In Mailchimp, open Profile -> Extras -> API keys and create a new API key.
|
|
21
|
+
2. Copy the full key including the trailing data-center suffix (e.g. `abc123...-us1`); the suffix selects the API host.
|
|
22
|
+
3. Store the key as a secret and reference it from config as `apiKey: secret("MAILCHIMP_API_KEY")`.
|
|
23
|
+
|
|
24
|
+
## Configuration
|
|
25
|
+
|
|
26
|
+
| Field | Type | Required | Description |
|
|
27
|
+
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| `apiKey` | secret | Yes | Mailchimp Marketing API key. The data-center suffix after the dash (e.g. `-us1`) selects the API host. Create one at Profile -> Extras -> API keys. |
|
|
29
|
+
| `resources` | array | No | Which Mailchimp resources to sync. Omit to sync all of them. |
|
|
30
|
+
|
|
31
|
+
## Resources
|
|
32
|
+
|
|
33
|
+
- **`mailchimp_campaign`** _(entity)_ - Campaigns (regular, plaintext, A/B, RSS, etc.) with status, type, subject line, sender, audience, send time, and total emails sent.
|
|
34
|
+
- Endpoint: `GET /campaigns`
|
|
35
|
+
- `status`: Campaign status (save, paused, schedule, sending, sent).
|
|
36
|
+
- `type`: Campaign type (regular, plaintext, absplit, rss, etc.).
|
|
37
|
+
- `subjectLine`: Email subject line.
|
|
38
|
+
- `title`: Internal campaign title.
|
|
39
|
+
- `fromName`: Sender display name.
|
|
40
|
+
- `replyTo`: Reply-to email address.
|
|
41
|
+
- `listId`: Audience (list) id the campaign targets.
|
|
42
|
+
- `listName`: Audience (list) display name.
|
|
43
|
+
- `createTime`: When the campaign was created (Unix ms).
|
|
44
|
+
- `sendTime`: When the campaign was sent (Unix ms).
|
|
45
|
+
- `emailsSent`: Total emails sent.
|
|
46
|
+
- **`mailchimp_list`** _(entity)_ - Audiences (lists) with member counts, engagement rates, and lifetime campaign count.
|
|
47
|
+
- Endpoint: `GET /lists`
|
|
48
|
+
- `name`: Audience name.
|
|
49
|
+
- `memberCount`: Number of subscribed members.
|
|
50
|
+
- `unsubscribeCount`: Number of unsubscribed members.
|
|
51
|
+
- `cleanedCount`: Number of cleaned addresses.
|
|
52
|
+
- `openRate`: Lifetime open rate as a fraction (0 to 1).
|
|
53
|
+
- `clickRate`: Lifetime click rate as a fraction (0 to 1).
|
|
54
|
+
- `campaignCount`: Number of campaigns sent to the audience.
|
|
55
|
+
- `listRating`: Mailchimp star rating (0 to 5).
|
|
56
|
+
- `createdAt`: When the audience was created (Unix ms).
|
|
57
|
+
- **`mailchimp_automation`** _(entity)_ - Automations (classic email workflows) with status, title, sender, audience, and lifetime emails sent.
|
|
58
|
+
- Endpoint: `GET /automations`
|
|
59
|
+
- `status`: Automation status (save, paused, sending).
|
|
60
|
+
- `title`: Automation title.
|
|
61
|
+
- `fromName`: Sender display name.
|
|
62
|
+
- `replyTo`: Reply-to email address.
|
|
63
|
+
- `listId`: Audience (list) id the automation targets.
|
|
64
|
+
- `listName`: Audience (list) display name.
|
|
65
|
+
- `emailsSent`: Total emails sent over the workflow lifetime.
|
|
66
|
+
- `createTime`: When the automation was created (Unix ms).
|
|
67
|
+
- `startTime`: When the automation was started (Unix ms).
|
|
68
|
+
- **`mailchimp_campaign_stats`** _(metric)_ - Per-campaign engagement stats (sent, opens, clicks, bounces, unsubscribes) timestamped at the campaign send time.
|
|
69
|
+
- Endpoint: `GET /reports`
|
|
70
|
+
- Unit: emails
|
|
71
|
+
- Dimensions: `campaignId`, `campaignTitle`, `campaignType`, `listId`, `opensTotal`, `uniqueOpens`, `openRate`, `clicksTotal`, `uniqueClicks`, `clickRate`, `hardBounces`, `softBounces`, `unsubscribed`
|
|
72
|
+
- One sample per campaign; value is the sent count, and every other counter is exposed in attributes. The scope is cleared and rewritten on every sync because the /reports endpoint has no `since` filter.
|
|
73
|
+
|
|
74
|
+
## Example
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import {
|
|
78
|
+
defineConfig,
|
|
79
|
+
defineDashboard,
|
|
80
|
+
defineMetric,
|
|
81
|
+
secret,
|
|
82
|
+
} from '@rawdash/core';
|
|
83
|
+
|
|
84
|
+
const mailchimp = {
|
|
85
|
+
name: 'mailchimp',
|
|
86
|
+
connectorId: 'mailchimp',
|
|
87
|
+
config: {
|
|
88
|
+
apiKey: secret('MAILCHIMP_API_KEY'),
|
|
89
|
+
},
|
|
90
|
+
};
|
|
91
|
+
|
|
92
|
+
export default defineConfig({
|
|
93
|
+
connectors: [mailchimp],
|
|
94
|
+
dashboards: {
|
|
95
|
+
marketing: defineDashboard({
|
|
96
|
+
widgets: {
|
|
97
|
+
emails_sent: {
|
|
98
|
+
kind: 'stat',
|
|
99
|
+
title: 'Emails sent (last 30d)',
|
|
100
|
+
metric: defineMetric({
|
|
101
|
+
connector: mailchimp,
|
|
102
|
+
shape: 'metric',
|
|
103
|
+
name: 'mailchimp_campaign_stats',
|
|
104
|
+
fn: 'sum',
|
|
105
|
+
}),
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
}),
|
|
109
|
+
},
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Rate limits
|
|
114
|
+
|
|
115
|
+
Mailchimp allows up to 10 simultaneous connections per account; per-endpoint rate limits are not advertised, so the connector keeps to sequential paginated requests.
|
|
116
|
+
|
|
117
|
+
## Limitations
|
|
118
|
+
|
|
119
|
+
- Per-campaign report stats are rewritten on every sync because the /reports endpoint has no `since` filter.
|
|
120
|
+
- Automations are synced as entities only; per-workflow open/click counts are out of scope.
|
|
121
|
+
- Member-level data, ecommerce stores, and landing pages are out of scope.
|
|
122
|
+
|
|
123
|
+
## Links
|
|
124
|
+
|
|
125
|
+
- [Rawdash docs](https://rawdash.dev/docs/connectors/)
|
|
126
|
+
- [Mailchimp API docs](https://mailchimp.com/developer/marketing/api/)
|
|
127
|
+
- [GitHub](https://github.com/rawdash/rawdash)
|
|
128
|
+
|
|
129
|
+
## License
|
|
130
|
+
|
|
131
|
+
Apache-2.0
|