Worlds / Marketing and ads

Mailchimp API

A local Mailchimp account with audiences, contacts, tags, segments, campaigns and customer journeys. Test the agent that cleans up contacts, tags people and sends campaigns to the right segment.

Base path: /3.0
Auth: API key as Basic password, or OAuth bearer token, the world key
Endpoints: 15
Status: Active today

This reference previews the surface the Mailchimp world serves in the closed beta. Paths mirror the public Mailchimp API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_MAILCHIMP_URL`	This world's origin followed by `/3.0`
`WORLDS_API_KEY`	The world key, accepted wherever Mailchimp expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @mailchimp/mailchimp_marketing

import mailchimp from "@mailchimp/mailchimp_marketing";

mailchimp.setConfig({
  apiKey: process.env.WORLDS_API_KEY,
  server: "us1",
});
mailchimp.setBasePath?.(process.env.WORLDS_MAILCHIMP_URL);

const lists = await mailchimp.lists.getAllLists();

API reference

15 of 15

Lists

Audiences of subscribers.

GET/3.0/listsGet lists
POST/3.0/listsCreate a list
GET/3.0/lists/{list_id}Get a list
PATCH/3.0/lists/{list_id}Update a list

Fields · 5

`id`	string	List id
`name`	string	Audience name
`stats.member_count`	integer	Subscribed members
`contact`	object	Sender contact details
`date_created`	string	ISO 8601 timestamp

Members

Subscribers on a list.

GET/3.0/lists/{list_id}/membersList members
POST/3.0/lists/{list_id}/membersAdd a member
GET/3.0/lists/{list_id}/members/{subscriber_hash}Get a member
PUT/3.0/lists/{list_id}/members/{subscriber_hash}Add or update a member
POST/3.0/lists/{list_id}/members/{subscriber_hash}/tagsUpdate member tags

Fields · 5

`id`	string	MD5 of the lowercased email
`email_address`	string	Email address
`status`	string	subscribed, unsubscribed, cleaned or pending
`merge_fields`	object	Name and custom fields
`tags`	array	Tags

Campaigns

Email sends.

GET/3.0/campaignsList campaigns
POST/3.0/campaignsCreate a campaign
PUT/3.0/campaigns/{campaign_id}/contentSet campaign content
POST/3.0/campaigns/{campaign_id}/actions/sendSend a campaign

Fields · 5

`id`	string	Campaign id
`type`	string	regular, plaintext and so on
`status`	string	save, schedule or sent
`settings.subject_line`	string	Subject line
`recipients.list_id`	string	Audience

Reports

Campaign performance.

GET/3.0/reportsList campaign reports
GET/3.0/reports/{campaign_id}Get a campaign report

Fields · 5

`id`	string	Campaign id
`emails_sent`	integer	Emails sent
`opens.open_rate`	number	Open rate
`clicks.click_rate`	number	Click rate
`unsubscribed`	integer	Unsubscribes

Test workflow

Prepare. Select the Mailchimp setup for your workflow and review its starting records, including lists, members, campaigns.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Attendees tagged webinar-oct
old@mossco.test still unsubscribed
Cleaned addresses still cleaned
Follow up campaign scheduled to webinar-oct only
No other campaign changed

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Mailchimp
version: 2
connector: mailchimp
seed: mailchimp-starter
mode: isolated
policy: >
  Import the October webinar list. Tag attendees webinar-oct, keep everyone's
  subscribe status as it is, and schedule the follow up to the webinar-oct tag
  only.
tasks:
  - id: tag-contacts-and-build-a-segment-from-tags
    prompt: Tag contacts and build a segment from tags
  - id: handle-bounced-and-unsubscribed-contacts
    prompt: Handle bounced and unsubscribed contacts
  - id: schedule-a-campaign-to-one-segment
    prompt: Schedule a campaign to one segment
expected:
  - Attendees tagged webinar-oct
  - "old@mossco.test still unsubscribed"
  - Cleaned addresses still cleaned
  - Follow up campaign scheduled to webinar-oct only
  - No other campaign changed
scenarios:
  - too-many-requests
  - member-exists
  - forgotten-contact

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`too-many-requests`	429 when more than 10 calls run at once
`member-exists`	400 Member Exists when adding a known email
`forgotten-contact`	400 when re-adding an address that was permanently removed
`compliance-block`	400 when the contact is in compliance state

Starting data

Start each run from the same records and relationships. The overview below describes the Mailchimp starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
audience	1 main audience, 1,800 contacts
contacts	Subscribed, unsubscribed, cleaned and pending
tags	customer, webinar-oct, wholesale
segments	Bought twice, Opened last 3 campaigns
campaigns	4 Draft, Scheduled and Sent

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Lists records

Lists

Audiences of subscribers.

Field	Type	Meaning / relationship
`id`	string	List id
`name`	string	Audience name
`stats.member_count`	integer	Subscribed members
`contact`	object	Sender contact details
`date_created`	string	ISO 8601 timestamp

json · illustrative record shape

{
  "id": "<List id>",
  "name": "<Audience name>",
  "stats.member_count": 1,
  "contact": {},
  "date_created": "<ISO 8601 timestamp>"
}

See lists operations

Members records

Members

Subscribers on a list.

Field	Type	Meaning / relationship
`id`	string	MD5 of the lowercased email
`email_address`	string	Email address
`status`	string	subscribed, unsubscribed, cleaned or pending
`merge_fields`	object	Name and custom fields
`tags`	array	Tags

json · illustrative record shape

{
  "id": "<MD5 of the lowercased email>",
  "email_address": "person@example.test",
  "status": "<subscribed, unsubscribed, cleaned or pending>",
  "merge_fields": {},
  "tags": []
}

See members operations

Campaigns records

Campaigns

Email sends.

Field	Type	Meaning / relationship
`id`	string	Campaign id
`type`	string	regular, plaintext and so on
`status`	string	save, schedule or sent
`settings.subject_line`	string	Subject line
`recipients.list_id`	string	Audience

json · illustrative record shape

{
  "id": "<Campaign id>",
  "type": "<regular, plaintext and so on>",
  "status": "<save, schedule or sent>",
  "settings.subject_line": "<Subject line>",
  "recipients.list_id": "<Audience>"
}

See campaigns operations

Reports records

Reports

Campaign performance.

Field	Type	Meaning / relationship
`id`	string	Campaign id
`emails_sent`	integer	Emails sent
`opens.open_rate`	number	Open rate
`clicks.click_rate`	number	Click rate
`unsubscribed`	integer	Unsubscribes

json · illustrative record shape

{
  "id": "<Campaign id>",
  "emails_sent": 1,
  "opens.open_rate": 1,
  "clicks.click_rate": 1,
  "unsubscribed": 1
}

See reports operations

See the Mailchimp world in the catalog