# Connecting to Mailchimp
Mailchimp is an all-in-one marketing platform that helps you manage and talk to your clients, customers, and other interested parties. Their approach to marketing focuses on healthy contact management practices, beautifully designed emails, unique automated workflows, and powerful data analysis. If you're a Mailchimp user, you can connect AWS Glue to your Mailchimp account. Then, you can use Mailchimp as a data source in your ETL jobs. Run these jobs to transfer data between Mailchimp and AWS services or other supported applications.
**Topics**
+ [AWS Glue support for Mailchimp](mailchimp-support.md)
+ [Policies containing the API operations for creating and using connections](mailchimp-configuring-iam-permissions.md)
+ [Configuring Mailchimp](mailchimp-configuring.md)
+ [Configuring Mailchimp connections](mailchimp-configuring-connections.md)
+ [Reading from Mailchimp entities](mailchimp-reading-from-entities.md)
+ [Mailchimp connection options](mailchimp-connection-options.md)
+ [Creating an Mailchimp account](mailchimp-create-account.md)
+ [Limitations](mailchimp-connector-limitations.md)
# AWS Glue support for Mailchimp
AWS Glue supports Mailchimp as follows:
**Supported as a source?**
Yes. You can use AWS Glue ETL jobs to query data from Mailchimp.
**Supported as a target?**
No.
**Supported Mailchimp API versions**
3.0
# Policies containing the API operations for creating and using connections
The following sample policy describes the required AWS permissions for creating and using connections. If you are creating a new role, create a policy that contains the following:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
------
If you don't want to use the preceding method, alternatively, use the following managed IAM policies:
+ [ AWSGlueServiceRole ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Grants access to resources that various AWS Glue processes require to run on your behalf. These resources include AWS Glue, Amazon S3, IAM, CloudWatch Logs, and Amazon EC2. If you follow the naming convention for resources specified in this policy, AWS Glue processes have the required permissions. This policy is typically attached to roles specified when defining crawlers, jobs, and development endpoints.
+ [ AWSGlueConsoleFullAccess ](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – Grants full access to AWS Glue resources when an identity that the policy is attached to uses the AWS Management console. If you follow the naming convention for resources specified in this policy, users have full console capabilities. This policy is typically attached to users of the AWS Glue console.
# Configuring Mailchimp
Before you can use AWS Glue to transfer from Mailchimp, you must meet the following requirements:
## Minimum requirements
+ You have an Mailchimp account with email and password. For more information about creating an account, see [Creating a Mailchimp account](mailchimp-create-account.md).
+ You must have AWS Account created with the service access to AWS Glue.
+ Ensure you have created one of the following resources. These resources provide credentials that AWS Glue uses to securely access your data when making authenticated calls to your account:
+ A Developer App that supports OAuth 2.0 authentication. For more information about creating a Developer App, see [Creating a Mailchimp account](mailchimp-create-account.md).
If you meet these requirements, you’re ready to connect AWS Glue to your Mailchimp account. For typical connections, you don't need do anything else in Mailchimp.
# Configuring Mailchimp connections
Mailchimp supports following two types for authentication mechanism:
+ Mailchimp supports the `AUTHORIZATION_CODE` grant type.
+ This grant type is considered “three-legged” `OAuth` as it relies on redirecting users to the third party authorization server to authenticate the user. It is used when creating connections via the AWS Glue Console. The user creating a connection may by default rely on a AWS Glue owned connected app where they do not need to provide any `OAuth` related information except for their Mailchimp Client ID and Client Secret. The AWS Glue Console will redirect the user to Mailchimp where the user must login and allow AWS Glue the requested permissions to access their Mailchimp instance.
+ Users may still opt to create their own connected app in Mailchimp and provide their own Client ID and Client Secret when creating connections through the AWS Glue Console. In this scenario, they will still be redirected to Mailchimp to login and authorize AWS Glue to access their resources.
+ For public Mailchimp documentation on creating a connected app for `AUTHORIZATION_CODE OAuth` flow, see [ Access Data on Behalf of Other Users with OAuth 2 ](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/?msockid=141ebf9ffb4d619525c3ad27fad660d6).
+ **Custom Auth** – For public Mailchimp documentation about generating the required API keys for custom authorization, see [ About API Keys](https://mailchimp.com/en/help/about-api-keys/?msockid=310fd0fe09d16afe034fc5de08d76b01).
To configure a Mailchimp connection:
1. In AWS Secrets Manager, create a secret with the following details:
+ `OAuth` auth – For customer managed connected app: Secret should contain the connected app Consumer Secret with `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` as key.
+ Custom auth – For customer managed connected app: Secret should contain the connected app Consumer Secret with “api\$1key” as key.
**Note**
It is a must to create a secret per connection in AWS Glue.
1. In AWS Glue Studio, create a connection under **Data Connections** by following the steps below:
1. Under **Connections**, select **Create connection**.
1. When selecting a **Data Source**, select Mailchimp.
1. Provide the Mailchimp `instanceUrl`.
1. Select the IAM role for which AWS Glue can assume and has permissions for following actions:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. Select Authentication Type to connect to Mailchimp:
+ For `OAuth` auth – Provide the Token URL, User Managed Client Application ClientId of the Mailchimp that you want to connect to.
+ For Custom auth – Select Authentication Type CUSTOM to connect to Mailchimp.
1. Select the `secretName` which you want to use for this connection in AWS Glue to put the tokens.
1. Select the network options if you want to use your network.
1. Grant the IAM role associated with your AWS Glue job permission to read `secretName`.
1. In your AWS Glue job configuration, provide `connectionName` as an Additional network connection.
# Reading from Mailchimp entities
**Prerequisites**
A Mailchimp Object you would like to read from. Refer the supported entities table below to check the available entities.
**Supported entities**
+ [Abuse-reports ](https://mailchimp.com/developer/marketing/api/campaign-abuse/)
+ [Automation](https://mailchimp.com/developer/marketing/api/automation/list-automations/)
+ [Campaigns](https://mailchimp.com/developer/marketing/api/campaigns/list-campaigns/)
+ [Click-details](https://mailchimp.com/developer/marketing/api/link-clickers/)
+ [Lists](https://mailchimp.com/developer/marketing/api/link-clickers/)
+ [Members](https://mailchimp.com/developer/marketing/api/list-segment-members/)
+ [Open-details](https://mailchimp.com/developer/marketing/api/list-members/)
+ [Segments](https://mailchimp.com/developer/marketing/api/list-segments/)
+ [Stores](https://mailchimp.com/developer/marketing/api/ecommerce-stores/list-stores/)
+ [Unsubscribed](https://mailchimp.com/developer/marketing/api/unsub-reports/)
| Entity | Can be Filtered | Supports Limit | Supports Order By | Supports Select \$1 | Supports Partitioning |
| --- | --- | --- | --- | --- | --- |
| Automation | Yes | Yes | Yes | Yes | Yes |
| Campaigns | No | No | No | No | No |
| Lists | Yes | Yes | No | Yes | Yes |
| Reports Abuse | No | Yes | No | Yes | Yes |
| Reports Open | No | Yes | No | Yes | Yes |
| Reports Click | Yes | Yes | No | Yes | Yes |
| Reports Unsubscribe | No | Yes | No | Yes | Yes |
| Segment | No | Yes | No | Yes | Yes |
| Segment Members | Yes | Yes | No | Yes | No |
| Stores | Yes | Yes | Yes | Yes | No |
**Example**
```
mailchimp_read = glueContext.create_dynamic_frame.from_options(
connection_type="mailchimp",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "stores",
"INSTANCE_URL": "https://us14.api.mailchimp.com",
"API_VERSION": "3.0"
})
```
**Mailchimp entity and field details**
+ [Abuse-reports ](https://mailchimp.com/developer/marketing/api/campaign-abuse/)
+ [Automation](https://mailchimp.com/developer/marketing/api/automation/list-automations/)
+ [Campaigns](https://mailchimp.com/developer/marketing/api/campaigns/list-campaigns/)
+ [Click-details](https://mailchimp.com/developer/marketing/api/link-clickers/)
+ [Lists](https://mailchimp.com/developer/marketing/api/link-clickers/)
+ [Members](https://mailchimp.com/developer/marketing/api/list-segment-members/)
+ [Open-details](https://mailchimp.com/developer/marketing/api/list-members/)
+ [Segments](https://mailchimp.com/developer/marketing/api/list-segments/)
+ [Stores](https://mailchimp.com/developer/marketing/api/ecommerce-stores/list-stores/)
+ [Unsubscribed](https://mailchimp.com/developer/marketing/api/unsub-reports/)
## Partitioning queries
You can provide the additional Spark options `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND`, and `NUM_PARTITIONS` if you want to utilize concurrency in Spark. With these parameters, the original query would be split into `NUM_PARTITIONS` number of sub-queries that can be executed by Spark tasks concurrently.
+ `PARTITION_FIELD`: the name of the field to be used to partition the query.
+ `LOWER_BOUND`: an **inclusive** lower bound value of the chosen partition field.
For the DateTime field, we accept the value in ISO format.
Example of valid value:
```
"2024-07-01T00:00:00.000Z"
```
+ `UPPER_BOUND`: an **exclusive** upper bound value of the chosen partition field.
+ `NUM_PARTITIONS`: the number of partitions.
The following table describes the entity partitioning field support details:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/glue/latest/dg/mailchimp-reading-from-entities.html)
Example:
```
read_read = glueContext.create_dynamic_frame.from_options(
connection_type="mailchimp",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "automations",
"API_VERSION": "3.0",
"INSTANCE_URL": "https://us14.api.mailchimp.com",
"PARTITION_FIELD": "create_time",
"LOWER_BOUND": "2024-02-05T14:09:30.115Z",
"UPPER_BOUND": "2024-06-07T13:30:00.134Z",
"NUM_PARTITIONS": "3"
}
```
# Mailchimp connection options
The following are connection options for Mailchimp:
+ `ENTITY_NAME`(String) – (Required) Used for Read/Write. The name of your Object in Mailchimp.
+ `INSTANCE_URL`(String) - (Required) A valid Mailchimp Instance URL.
+ `API_VERSION`(String) - (Required) Used for Read. Mailchimp Engage Rest API version you want to use. For example: 3.0.
+ `SELECTED_FIELDS`(List) - Default: empty(SELECT \$1). Used for Read. Columns you want to select for the object.
+ `FILTER_PREDICATE`(String) - Default: empty. Used for Read. It should be in the Spark SQL format.
+ `QUERY`(String) - Default: empty. Used for Read. Full Spark SQL query.
+ `PARTITION_FIELD`(String) - Used for Read. Field to be used to partition query.
+ `LOWER_BOUND`(String)- Used for Read. An inclusive lower bound value of the chosen partition field.
+ `UPPER_BOUND`(String) - Used for Read. An exclusive upper bound value of the chosen partition field.
+ `NUM_PARTITIONS`(Integer) - Default: 1. Used for Read. Number of partitions for read.
# Creating an Mailchimp account
1. Navigate to the [Mailchimp login page](https://login.mailchimp.com/?locale=en), enter your email ID and password, and then choose **Sign up**.
1. Open the confirmation email from Mailchimp, and choose the confirmation link to verify your account.
**Note**
The time it takes to receive the activation email may vary. If you haven't received the activation email, check your spam folder, and read our activation email troubleshooting tips. Mailchimp blocks signups from role-based email addresses such as, [admin@pottedplanter.com](mailto:admin@pottedplanter.com) or [security@example.com](mailto:security@example.com).
The first time you log in to your account, Mailchimp asks for required information. Mailchimp uses this information to help ensure your account is compliant with their Terms of Use and to provide guidance that's relevant to you and your company's needs.
1. Enter your information, follow the prompts to finish the activation process, and get started in your new Mailchimp account.
**Registering an `OAuth2.0` application**
1. Navigate to the [Mailchimp login page](https://login.mailchimp.com/?locale=en), enter your email ID and password, and choose **Log in**.
1. Select the **User** icon in the upper-right corner, and then choose **Account and billing** from the dropdown menu.
1. Select **Extras** and choose **Registered apps** from the dropdown menu.
1. Locate and choose **Register An App**.
1. Enter the following details:
+ **App name** – Name of the app.
+ **Company / Organization** – Name of your Company or Organization.
+ **App website** – Website of the app.
+ **Redirect URI** – A Redirect URI pattern is a URI path (or comma-separated list of paths) to which Mailchimp can redirect (if requested) when the login flow is complete. For example, `https://ap-southeast-2\\.console\\.aws\\.amazon\\.com`
1. Choose **Create**.
1. The **Client ID** and **Client Secret** will now be visible. Copy and save them in a secure location. Then, choose **Done**.
**Note**
Your Client ID and Client Secret strings are credentials used to establish a connection with this connector when using AppFlow or AWS Glue.
**Generating an API key**
1. Navigate to the [Mailchimp login page](https://login.mailchimp.com/?locale=en), enter your email ID and password, and choose **Log in**.
1. Select the **User** icon in the upper-right corner, and then choose **Account and billing** from the dropdown menu.
1. Select **Extras** and choose **API keys** from the dropdown menu.
1. Choose **Create A Key**.
1. Enter a name for the key and choose **Generate Key**.
The next page displays the generated API key.
1. Copy your key, store it securely, and choose **Done**.
# Limitations
The following are limitations for the Mailchimp connector:
+ Filtration is only supported by `Campaigns`, `Automations`, `Lists`, `Open Details`, `Members`, and `Segments` entities.
+ While using a filter on `DateTime` datatype field, you must pass values in this format: `yyyy-mm-ddThh:MM:ssZ`