Skip to content
Docs
Marketing

Mailchimp

Let hires check your Mailchimp audiences and reports, prepare campaigns, and send or schedule them once a person approves.

Explore 8 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Mailchimp, a hire can:

  • list your audiences and how many contacts each has,
  • look up contacts, without seeing who they are (see below),
  • list campaigns and read one: subject, sender, audience, what it says, and its report once sent (opens, clicks, bounces, unsubscribes),
  • prepare a campaign as a draft, and change a draft,
  • send a campaign now, or schedule it, once a person approves.

Contacts stay private

Roster only asks Mailchimp for a contact's ID, address, status and when they joined, and hires see the address masked, like j***@acme.com. Names, merge fields, locations and IP addresses never leave Mailchimp.

1. Make an API key in Mailchimp

Straight there: Mailchimp's API keys (sign in if asked).

  1. In Mailchimp, open your profile, then Extras → API keys, and click Create A Key. Name it Roster.
  2. Copy the key. It ends with your data centre, like -us21.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Mailchimp and choose it.
  2. API key: paste it.
  3. From name: your business's name, as subscribers see it.
  4. Reply-to address: where replies go, at a domain you've verified in Mailchimp.
  5. Click Connect.

Roster checks the key when you click Connect. If what you paste doesn't look like a key (a Mailchimp API key ends with your data centre, like -us21), the form says so straight away. Once it's accepted, the connection shows Connected as your Mailchimp account's name. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on Mailchimp:

  • Read only: audiences, contacts, campaigns and reports.
  • Read and write: also prepare and change drafts, and send or schedule campaigns (always with approval).
  • Audiences: audience names or IDs it may use. It can only look up contacts in these, and only read, change or send campaigns to them. Leave it empty for every audience.

Sending always asks first

A campaign goes to everyone in its audience and can't be taken back, so sending or scheduling one waits for a person's approval. The approver sees the subject, the audience and the campaign's version; if anyone changes the campaign after that, Roster won't send it. Drafts never ask. Mailchimp schedules on the quarter hour (:00, :15, :30, :45).

If something goes wrong

  • "Your API key may be invalid": the key was deleted, or copied without its -us21 ending.
  • "Only a draft can be sent or scheduled": the campaign is already scheduled, sending or sent.
  • Mailchimp refuses to send a campaign it finds incomplete (no content, an unverified reply-to domain); the hire passes on Mailchimp's reason.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Mailchimp and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Mailchimp: Profile → Extras → API keys → Create a key. It ends with your data centre, like -us21.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Mailchimp connection fields
FieldWhat to provide
API key
token
Required · sealed secret		In Mailchimp: Profile → Extras → API keys → Create a key. It ends with your data centre, like -us21.
From name
fromName
Required		Your business's name, as subscribers see it on every campaign.
Reply-to address
fromEmail
Required		Where replies go. Use an address at a domain you've verified in Mailchimp.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Mailchimp per-hire limits
FieldWhat to provide
Audiences
lists
Optional		Audience names or IDs it may read and write to, one per line. Leave empty for every audience.

Actions

8 actions: 4 only read and 4 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

8 of 8 actions. Open an action for its arguments and full input schema.

list_listsRead only

Mailchimp audiences this hire may use, with how many subscribers each has.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_subscribersRead only

Subscribers of a audience, or anyone matching words such as an address: each with a masked address (j***@acme.com), status, audiences and when they joined. Never names or other personal details.

Approval: Uses your workspace and hire approval settings.

Arguments for list_subscribers
ArgumentTypeDetails
listOptionalstringthe audience's name or ID
searchOptionalstringan address or words to look for
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "list": {
      "description": "the audience's name or ID",
      "type": "string",
      "maxLength": 200
    },
    "search": {
      "description": "an address or words to look for",
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
list_campaignsRead only

Mailchimp campaigns, newest first: status (draft, scheduled, sending, paused, sent, cancelled), audiences and when.

Approval: Uses your workspace and hire approval settings.

Arguments for list_campaigns
ArgumentTypeDetails
statusOptional"draft" | "scheduled" | "sending" | "paused" | "sent" | "cancelled"See input schema below.
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "scheduled",
        "sending",
        "paused",
        "sent",
        "cancelled"
      ]
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
get_campaignRead only

One Mailchimp campaign: subject, sender, audiences, what it says, its report once sent, and its version (needed to send or schedule it).

Approval: Uses your workspace and hire approval settings.

Arguments for get_campaign
ArgumentTypeDetails
campaignRequiredstringthe campaign's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "campaign": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "the campaign's ID"
    }
  },
  "required": [
    "campaign"
  ]
}
create_draftRead and write

Prepare a campaign as a draft in Mailchimp for a person to check: subject, audiences and content. Nobody receives anything. It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: Uses your workspace and hire approval settings.

Arguments for create_draft
ArgumentTypeDetails
nameRequiredstringan internal name for the campaign
subjectRequiredstringSee input schema below.
listsRequiredstring[]the audiences (names or IDs) it goes to
bodyRequiredstringthe email's content
formatOptional"text" | "html"text: plain text, paragraphs on blank lines; html: your HTMLDefault: "text"
preview_textOptionalstringthe line inboxes show after the subject
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "an internal name for the campaign"
    },
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "lists": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "description": "the audiences (names or IDs) it goes to"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100000,
      "description": "the email's content"
    },
    "format": {
      "default": "text",
      "description": "text: plain text, paragraphs on blank lines; html: your HTML",
      "type": "string",
      "enum": [
        "text",
        "html"
      ]
    },
    "preview_text": {
      "description": "the line inboxes show after the subject",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "name",
    "subject",
    "lists",
    "body"
  ]
}
update_draftRead and write

Change a draft Mailchimp campaign: its name, subject, audiences, preview text or content. Only drafts can change; nobody receives anything.

Approval: Uses your workspace and hire approval settings.

Arguments for update_draft
ArgumentTypeDetails
campaignRequiredstringthe campaign's ID
nameOptionalstringan internal name for the campaign
subjectOptionalstringSee input schema below.
listsOptionalstring[]the audiences (names or IDs) it goes to
bodyOptionalstringthe email's content
formatOptional"text" | "html"the body's format, with body (default text)
preview_textOptionalstringthe line inboxes show after the subject
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "campaign": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "the campaign's ID"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "an internal name for the campaign"
    },
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "lists": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "description": "the audiences (names or IDs) it goes to"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100000,
      "description": "the email's content"
    },
    "format": {
      "description": "the body's format, with body (default text)",
      "type": "string",
      "enum": [
        "text",
        "html"
      ]
    },
    "preview_text": {
      "description": "the line inboxes show after the subject",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "campaign"
  ]
}
send_campaignRead and write

Send a draft Mailchimp campaign now to everyone on its audiences. It's public and can't be taken back, so it waits for a person's approval: Roster asks in the thread with the subject, audiences and version, and sends exactly that version, once, when they approve. It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: Always asks for approval.

Arguments for send_campaign
ArgumentTypeDetails
campaignRequiredstringthe campaign's ID
subjectRequiredstringits subject, exactly as get_campaign shows it
listsRequiredstring[]the audiences it goes to, as get_campaign shows them
versionRequiredstringits version, from get_campaign
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "campaign": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "the campaign's ID"
    },
    "subject": {
      "type": "string",
      "maxLength": 300,
      "description": "its subject, exactly as get_campaign shows it"
    },
    "lists": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "description": "the audiences it goes to, as get_campaign shows them"
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9a-f]{10}$",
      "description": "its version, from get_campaign"
    }
  },
  "required": [
    "campaign",
    "subject",
    "lists",
    "version"
  ]
}
schedule_campaignRead and write

Schedule a draft Mailchimp campaign to go out at a time. It's public, so it waits for a person's approval, as send_campaign does. It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: Always asks for approval.

Arguments for schedule_campaign
ArgumentTypeDetails
campaignRequiredstringthe campaign's ID
subjectRequiredstringits subject, exactly as get_campaign shows it
listsRequiredstring[]the audiences it goes to, as get_campaign shows them
versionRequiredstringits version, from get_campaign
atRequiredstringwhen, ISO 8601 with a time zone, e.g. 2026-11-10T09:00:00+04:00
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "campaign": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "the campaign's ID"
    },
    "subject": {
      "type": "string",
      "maxLength": 300,
      "description": "its subject, exactly as get_campaign shows it"
    },
    "lists": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "description": "the audiences it goes to, as get_campaign shows them"
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9a-f]{10}$",
      "description": "its version, from get_campaign"
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "when, ISO 8601 with a time zone, e.g. 2026-11-10T09:00:00+04:00"
    }
  },
  "required": [
    "campaign",
    "subject",
    "lists",
    "version",
    "at"
  ]
}

Watches and incoming events

  • No built-in watch is declared. Give a hire a scheduled responsibility if it should check this service regularly.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

listmonk

Let hires prepare newsletters in your own listmonk, check lists and subscribers, and send or schedule campaigns once a person approves.

Tally

Forms and their submissions in Tally.

On this page

1. Make an API key in Mailchimp2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference