import { Tabs, Callout, Steps } from "nextra/components";

# Mailchimp

The Mailchimp auth provider enables tools and agents to call [Mailchimp Marketing APIs](https://mailchimp.com/developer/marketing/api/) on behalf of a user using OAuth 2.0 authentication.

<Callout>
  Want to quickly get started with Mailchimp in your agent or AI app? The
  pre-built [Arcade Mailchimp Marketing MCP Server](/resources/integrations/productivity/mailchimp-marketing-api)
  is what you want!
</Callout>

### What's documented here

This page describes how to use and configure Mailchimp auth with Arcade.

This auth provider is used by:

- The [Arcade Mailchimp Marketing MCP Server](/resources/integrations/productivity/mailchimp-marketing-api), which provides pre-built tools for interacting with Mailchimp
- Your [app code](#using-mailchimp-auth-in-app-code) that needs to call the Mailchimp API
- Or, your [custom tools](#using-mailchimp-auth-in-custom-tools) that need to call the Mailchimp API

## Configuring Mailchimp auth

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

In a production environment, you will most likely want to use your own Mailchimp app credentials. This way, your users will see your application's name requesting permission.

Before showing how to configure your Mailchimp app credentials, let's go through the steps to create a Mailchimp app.

### Create a Mailchimp app

To integrate with Mailchimp's API, you'll need to register an OAuth application:

<Steps>

#### Log into your Mailchimp account

1. Navigate to [mailchimp.com](https://mailchimp.com) and log in to your account
2. Go to **Account** > **Extras** > **Registered Apps**
3. Alternatively, you can directly access the [Registered Apps page](https://admin.mailchimp.com/account/oauth2/)

#### Register a new OAuth application

1. Click on **Register an App**
2. Fill in the required details:
   - **Application Name**: Choose a descriptive name for your application
   - **Company/Organization**: Enter your company or organization name
   - **Website URL**: Your application's website URL
   - **Description**: Brief description of your application
   - **Redirect URI**: Add the redirect URL generated by Arcade (see configuration section below)
     - This is the URL where Mailchimp will redirect users after authorization
     - For development, you can use `http://localhost:9099/oauth/callback` or your Arcade instance URL

#### Save your credentials

1. After registration, you'll receive your **Client ID** and **Client Secret**
2. **Important**: Copy and save these credentials immediately in a secure location
3. You can always view your Client ID later, but the Client Secret should be stored securely

</Steps>

For detailed instructions, refer to Mailchimp's [OAuth 2.0 documentation](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/) and [API documentation](https://mailchimp.com/developer/marketing/api/).

Next, add the Mailchimp app to Arcade.

## Configuring your own Mailchimp Auth Provider in Arcade

<Tabs items={["Dashboard GUI", "Configuration File"]}>
<Tabs.Tab>

### Configure Mailchimp Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **OAuth 2.0** tab at the top.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "arcade-mailchimp").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your Mailchimp app.
- Configure the OAuth 2.0 endpoints:
  - **Authorization URL**: `https://login.mailchimp.com/oauth2/authorize`
  - **Token URL**: `https://login.mailchimp.com/oauth2/token`
- Note the **Redirect URL** generated by Arcade. This must be set as your Mailchimp app's Redirect URI.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

</Tabs.Tab>

<Tabs.Tab>

### Configure Mailchimp Auth Using Configuration File

<Callout type="info">
  This method is only available when you are [self-hosting the
  engine](/guides/deployment-hosting/on-prem
</Callout>

<Steps>

#### Set environment variables

Set the following environment variables:

```bash
export MAILCHIMP_CLIENT_ID="<your client ID>"
export MAILCHIMP_CLIENT_SECRET="<your client secret>"
```

Or, you can set these values in a `.env` file:

```bash
MAILCHIMP_CLIENT_ID="<your client ID>"
MAILCHIMP_CLIENT_SECRET="<your client secret>"
```

#### Edit the Engine configuration

Edit the `engine.yaml` file and add a new item to the `auth.providers` section:

```yaml
auth:
  providers:
    - id: arcade-mailchimp
      description: Mailchimp OAuth 2.0 provider
      enabled: true
      type: oauth2
      client_id: ${env:MAILCHIMP_CLIENT_ID}
      client_secret: ${env:MAILCHIMP_CLIENT_SECRET}
      oauth2:
        authorize_request:
          endpoint: "https://login.mailchimp.com/oauth2/authorize"
          params:
            response_type: code
            client_id: "{{client_id}}"
            redirect_uri: "{{redirect_uri}}"
            state: "{{state}}"
        token_request:
          endpoint: "https://login.mailchimp.com/oauth2/token"
          params:
            grant_type: authorization_code
            client_id: "{{client_id}}"
            client_secret: "{{client_secret}}"
            redirect_uri: "{{redirect_uri}}"
          response_content_type: application/json
```

</Steps>

</Tabs.Tab>
</Tabs>

When you use tools that require Mailchimp auth using your Arcade account credentials, Arcade will automatically use this Mailchimp OAuth provider. If you have multiple Mailchimp providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

## Using Mailchimp auth in app code

Use the Mailchimp auth provider in your own agents and AI apps to get a user token for the Mailchimp API. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.

Use `client.auth.start()` to get a user token for the Mailchimp API:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {8-12}
from arcadepy import Arcade

client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable

user_id = "{arcade_user_id}"

# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="arcade-mailchimp"
)

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)

token = auth_response.context.token
# Do something interesting with the token...
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {8-11}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade();

const userId = "{arcade_user_id}";

// Start the authorization process
const authResponse = await client.auth.start(userId, "arcade-mailchimp");

if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}

// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);

const token = authResponse.context.token;
// Do something interesting with the token...
```

</Tabs.Tab>

</Tabs>

### Getting the API endpoint

Mailchimp requires you to determine the correct API endpoint for each user. After obtaining the access token, make a request to the metadata endpoint:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python
import httpx

# Get the user's API endpoint
async with httpx.AsyncClient() as client:
    metadata_response = await client.get(
        "https://login.mailchimp.com/oauth2/metadata",
        headers={"Authorization": f"Bearer {token}"}
    )
    metadata = metadata_response.json()
    api_endpoint = metadata["api_endpoint"]

# Now use the api_endpoint for all API calls
# Example: f"{api_endpoint}/3.0/lists"
```

</Tabs.Tab>

<Tabs.Tab>

```javascript
// Get the user's API endpoint
const metadataResponse = await fetch(
  "https://login.mailchimp.com/oauth2/metadata",
  {
    headers: { Authorization: `Bearer ${token}` }
  }
);
const metadata = await metadataResponse.json();
const apiEndpoint = metadata.api_endpoint;

// Now use the apiEndpoint for all API calls
// Example: `${apiEndpoint}/3.0/lists`
```

</Tabs.Tab>

</Tabs>

## Using Mailchimp auth in custom tools

You can use the pre-built [Arcade Mailchimp Marketing MCP Server](/resources/integrations/productivity/mailchimp-marketing-api) to quickly build agents and AI apps that interact with Mailchimp.

If the pre-built tools in the Mailchimp MCP Server don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Mailchimp API.

Use the `OAuth2()` auth class to specify that a tool requires authorization with Mailchimp. The `context.authorization.token` field will be automatically populated with the user's Mailchimp token:

```python {8-12,24}
from typing import Annotated

import httpx
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import OAuth2


@tool(
    requires_auth=OAuth2(provider_id="arcade-mailchimp")
)
async def get_mailchimp_lists(
    context: ToolContext,
) -> Annotated[dict, "The user's Mailchimp lists."]:
    """
    Retrieve all mailing lists from the authenticated user's Mailchimp account.
    """
    # First, get the API endpoint for this user
    async with httpx.AsyncClient() as client:
        metadata_response = await client.get(
            "https://login.mailchimp.com/oauth2/metadata",
            headers={"Authorization": f"Bearer {context.authorization.token}"}
        )
        api_endpoint = metadata_response.json()["api_endpoint"]

        # Now get the lists
        response = await client.get(
            f"{api_endpoint}/3.0/lists",
            headers={"Authorization": f"Bearer {context.authorization.token}"}
        )
        response.raise_for_status()
        return dict(response.json())
```

<Callout type="info">
  **Important**: Mailchimp access tokens do not expire unless the user revokes access. However, it's good practice to handle potential errors gracefully and provide users with options to re-authenticate if necessary.
</Callout>

For more details about Mailchimp's authentication, refer to the [Mailchimp OAuth 2.0 documentation](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/).