Mailchimp

The Mailchimp auth provider enables tools and agents to call Mailchimp Marketing APIs  on behalf of a user using OAuth 2.0 authentication.

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, which provides pre-built tools for interacting with Mailchimp
• Your app code that needs to call the Mailchimp API
• Or, your custom tools that need to call the Mailchimp API

Configuring Mailchimp auth

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:

For detailed instructions, refer to Mailchimp’s OAuth 2.0 documentation  and API documentation .

Next, add the Mailchimp app to Arcade.

Configuring your own Mailchimp Auth Provider in Arcade

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

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

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

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 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 to understand how this works.

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

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...

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...

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:

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"

// 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`

Using Mailchimp auth in custom tools

You can use the pre-built Arcade Mailchimp Marketing MCP Server 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 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:

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())

For more details about Mailchimp’s authentication, refer to the Mailchimp OAuth 2.0 documentation .