{"id":20655008,"url":"https://github.com/hdoro/gatsby-source-mailchimp","last_synced_at":"2025-04-19T11:52:03.238Z","repository":{"id":57245002,"uuid":"156602072","full_name":"hdoro/gatsby-source-mailchimp","owner":"hdoro","description":"Source plugin to fetch campaigns from Mailchimp into Gatsby","archived":false,"fork":false,"pushed_at":"2018-11-21T21:06:14.000Z","size":27,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-29T07:33:27.622Z","etag":null,"topics":["gatsby","mailchimp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hdoro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-07T20:08:41.000Z","updated_at":"2020-09-19T15:32:44.000Z","dependencies_parsed_at":"2022-09-01T06:10:46.343Z","dependency_job_id":null,"html_url":"https://github.com/hdoro/gatsby-source-mailchimp","commit_stats":null,"previous_names":["hcavalieri/gatsby-source-mailchimp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdoro%2Fgatsby-source-mailchimp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdoro%2Fgatsby-source-mailchimp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdoro%2Fgatsby-source-mailchimp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdoro%2Fgatsby-source-mailchimp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hdoro","download_url":"https://codeload.github.com/hdoro/gatsby-source-mailchimp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249688039,"owners_count":21311159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gatsby","mailchimp"],"created_at":"2024-11-16T18:08:16.050Z","updated_at":"2025-04-19T11:52:03.207Z","avatar_url":"https://github.com/hdoro.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gatsby-source-mailchimp\n\nUse your [Mailchimp API](https://developer.mailchimp.com) key to download your campaigns into [Gatsby](https://www.gatsbyjs.org/)'s GraphQL data layer!\n\n⚠ **Please note:** This plugin was made out of a specific necessity, so it doesn't cover all of Mailchimp's data sources, focusing only on campaigns. If you want to add extra functionalities, feel free to [create a PR](https://github.com/hcavalieri/gatsby-source-mailchimp/pulls) and contribute :smile:\n\n## Table of content\n\n- [Basic Usage](#basic-usage)\n- [Options](#options)\n- [Caveats](#caveats)\n- [Todo](#todo)\n- [License](#license)\n\n## Basic usage\n\n```\nyarn add gatsby-source-mailchimp\n# or\nnpm i gatsby-source-mailchimp --save\n```\n\n```js\n// in your gatsby-config.js\nmodule.exports = {\n  // ...\n  plugins: [\n    {\n      resolve: 'gatsby-source-mailchimp',\n      options: {\n        // Avoid including your key directly in your file.\n        // Instead, opt for adding them to .env files for extra\n        // security ;)\n        key: 'asd712jdas90122jdas90122jkadsd1-usXX',\n        rootURL: 'https://usXX.api.mailchimp.com/3.0',\n      },\n    },\n  ],\n  // ...\n};\n```\n\nGo through http://localhost:8000/___graphql after running `gatsby develop` to understand the created data and create a new query and checking available collections and fields by typing `CTRL + SPACE`.\n\n## Options\n\n| Options        | Type             | Default                   | Description                                                                                                                                                                                     |\n| -------------- | ---------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| key            | string           |                           | **[required]** Your API key                                                                                                                                                                     |\n| rootURL        | string           |                           | **[required]** Your key's root API URL. Usually in the format `https://usXX.api.mailchimp.com/3.0`                                                                                              |\n| authUsername   | string           | `GatsbyChimp`             | In case you want to name your requests, fill this value.                                                                                                                                        |\n| campaignFields | array of strings | See the [section below](#default-campaignFields-value) | Which fields to fetch from campaigns' metadata. See [Mailchimp's documentation on campaigns fields](https://developer.mailchimp.com/documentation/mailchimp/reference/campaigns)                |\n| contentFields  | array of strings | `['html']`                | Which fields to fetch from campaigns' content. See [Mailchimp's documentation on campaign content fields](https://developer.mailchimp.com/documentation/mailchimp/reference/campaigns/content/) |\n| nodeType       | string           | `MailchimpCampaign`       | How to name campaign nodes in GraphQL                                                                                                                                                           |\n| count          | string           | `30`                      | Number of campaigns to fetch. **Use `0` in order to fetch them all**                                                                                                                            |\n\n### Default `campaignFields` value\n\nIn terms of metadata, I believe most users will only need the campaign's `type` and `status` for filtering; `title` for internal usage; `send_time` for displaying dates for users; and `subject_line` and `preview_text` for showing a preview of the campaign. For such, the default fields are as follow:\n\n```js\nconst defaultCampaignsFields = [\n  'campaigns.type',\n  'campaigns.status',\n  'campaigns.send_time',\n  'campaigns.settings.subject_line',\n  'campaigns.settings.preview_text',\n  'campaigns.settings.title',\n];\n```\n\nYou can refer to [Mailchimp's documentation on campaigns](https://developer.mailchimp.com/documentation/mailchimp/reference/campaigns) in order to explore what other fields you can fetch, but be aware that you'll have to include these in your custom `campaignFields` if you want them to show up in results!\n\n## Using .env variables to hide your key\n\nIf you don't want to attach your API key to the repo, you can easily store it in .env files by doing the following:\n\n```js\n// In your .env file\nMAILCHIMP_KEY = 'asd712jdas90122jdas90122jkadsd1-usXX';\n\n// In your gatsby-config.js file\nrequire('dotenv').config({\n  path: `.env.${process.env.NODE_ENV}`,\n});\n\nmodule.exports = {\n  // ...\n  plugins: [\n    {\n      resolve: 'gatsby-source-mailchimp',\n      options: {\n        key: process.env.MAILCHIMP_KEY,\n        rootURL: 'https://usXX.api.mailchimp.com/3.0',\n        // ...\n      },\n    },\n  ],\n  // ...\n};\n```\n\nThis example is based off [Gatsby Docs' implementation](https://next.gatsbyjs.org/docs/environment-variables).\n\n## Caveats\n\nAs of now, the only known caveat is that, in order to preserve cache and avoid fetching the HTML content for each campaign every single time (which takes from 20s to 1m for 50 large campaigns), the plugin uses Gatsby's cache in a way that **considers changes made only to the `campaignFields`**. If you make a minor change to your HTML, as it stands, you'll have to change some of the campaign metadata that you're pulling into your site.\n\nUnfortunately, Mailchimp doesn't offer a `last_edited` field, so all we can do for now is to avoid caching alltogether. I haven't added a flag for this because it seems quite unnecessary, but feel free to create an optional `avoidCaching` param if you need!\n\n## Reference\n\nThe process to save campaigns in `gatsby-node.js` is as follows:\n\n1. We hit the `/campaigns/` endpoint with due limits and pagination (set by user configuration);\n2. This returns each campaign's metadata, which is used to check the cache.\n3. If it's in cache, then we're good, else we add a request to its content to an array;\n4. We run `Promise.all` with this array and iterate over it to get each campaign's content;\n5. Finally, we join the metadata and content and create the node, setting a new entry to the cache :wink:.\n\n## TODO\n\n- Explore better ways to cache the content.\n- Concurrent requests in a way that respects Mailchimp's 10 requests/minute limitation\n\n## License\n\nI'm not very literate on licensing, so I just went with **MIT**, if you have any considerations just let me know! Oh, and, of course, feel free to contribute to this plugin, even bug reports are welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhdoro%2Fgatsby-source-mailchimp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhdoro%2Fgatsby-source-mailchimp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhdoro%2Fgatsby-source-mailchimp/lists"}