ioLoop Docs

Appearance

$io.mailchimp ​

Server API reference.

Functions ​

$io.mailchimp.addTagsToMember ​

Add one or more tags to a member in a specific Mailchimp audience (activates tags).

Usage ​

js
$io.mailchimp.addTagsToMember(connectionName, listId, emailOrHash, tags, customRequestProperties)

Description ​

Adds tags to a member via Mailchimp Marketing API (POST /3.0/lists/{list_id}/members/{subscriber_hash}/tags).

  • emailOrHash can be a plain email (normalized and MD5-hashed internally) or a precomputed subscriber_hash.
  • tags must be a non-empty array of strings. Each tag is sent as { name: <tag>, status: 'active' }.
  • This call is idempotent for already-active tags (re-adding keeps them active).
  • Advanced per-call options (timeouts, headers, etc.) can be passed via customRequestProperties.

To confirm tags, read them back using GET /3.0/lists/{list_id}/members/{subscriber_hash}/tags.

Usage Scenarios ​

  • Flag contacts for lifecycle or campaign targeting (e.g., 'VIP', 'Onboarding')
  • Batch-tag newly imported subscribers
  • Apply behavioral tags after an action (purchase, webinar signup, etc.)

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

listId ​

Type: String

Required: Yes

Target audience (list) ID.

emailOrHash ​

Type: String

Required: Yes

Member identifier: email address or subscriber_hash (MD5 of trimmed, lowercased email).

tags ​

Type: Array<String>

Required: Yes

Non-empty array of tag names to activate for the member.

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: null } on success. Note: Mailchimp typically returns 204 No Content for this endpoint, so data is usually null. For verification, issue a follow-up GET to the member's /tags endpoint.

$io.mailchimp.createOrUpdateMember ​

Upsert a member in a Mailchimp audience (PUT to members/{subscriber_hash}); creates if new, updates if existing.

Usage ​

js
$io.mailchimp.createOrUpdateMember(connectionName, listId, email, fields, statusIfNew, customRequestProperties)

Description ​

Performs a Mailchimp upsert using PUT /3.0/lists/{list_id}/members/{subscriber_hash}.

  • subscriber_hash is computed from the trimmed, lowercased email via MD5.
  • Create (new): Mailchimp requires email_address and status_if_new (e.g., 'subscribed' or 'pending' for double opt-in).
  • Update (existing): Member is updated per Mailchimp semantics (fields in the payload are applied/merged).
  • Pass additional member properties in fields (e.g., merge_fields, language, vip, etc.).
  • Advanced per-call options (timeouts, headers, etc.) can be provided via customRequestProperties.

Usage Scenarios ​

  • Subscribe a new contact to a specific audience
  • Idempotently update merge fields or profile attributes
  • Implement double opt-in by creating with status 'pending'

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

listId ​

Type: String

Required: Yes

Target audience (list) ID.

email ​

Type: String

Required: Yes

Member's email address (used to compute subscriber_hash).

fields ​

Type: Object

Required: No

Additional member fields to set (e.g., { merge_fields: { FNAME: 'Ada' }, language: 'en', vip: false }). Defaults to {}.

statusIfNew ​

Type: String

Required: No

Status when creating a new member. Common values: 'subscribed', 'pending'. Default is 'subscribed'.

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpMemberResponse }.

MailchimpMemberResponse mirrors JSON from PUT /3.0/lists/{list_id}/members/{subscriber_hash} and typically includes:

  • id: Member ID (UUID)
  • email_address: Normalized email
  • status: Current subscription status
  • merge_fields: Object of custom fields (if present)
  • last_changed: ISO timestamp of the last update

Example minimal response: { "id": "abc123", "email_address": "[email protected]", "status": "subscribed", "merge_fields": { "FNAME": "Ada", "LNAME": "Lovelace" }, "last_changed": "2025-07-20T12:34:56+00:00" }

$io.mailchimp.execApiRequest ​

Low-level Mailchimp API executor that forwards an authenticated request (via the chosen connection) to any Marketing API endpoint.

Usage ​

js
$io.mailchimp.execApiRequest(connectionName, path, method, data, queryParams, customRequestProperties)

Description ​

Executes a direct, authenticated Mailchimp Marketing API call using the saved credentials from the specified connectionName.

  • path may be a relative API path (e.g., /3.0/lists) or a full URL (e.g., https://us14.api.mailchimp.com/3.0/lists). The underlying instance will normalize relative paths and bind the correct datacenter.
  • method must be one of: GET, POST, PUT, PATCH, DELETE.
  • data is the request body object for write methods (POST, PUT, PATCH). For GET/DELETE, pass {}.
  • queryParams is an object of query string parameters (e.g., { count: 100, offset: 0, fields: "..." }).
  • customRequestProperties provides advanced Axios options (e.g., timeout, headers, etc.) if needed.

Validation & behavior:

  • The underlying instance enforces: no request body for GET/DELETE; method/path validation; URL normalization.
  • Errors are surfaced with HTTP status when available (e.g., "HTTP 400: {...}").
  • Pagination typically follows Mailchimp's count + offset pattern; consult official docs for each endpoint.

Usage Scenarios ​

  • Call arbitrary Mailchimp endpoints not yet wrapped by helpers
  • Prototype and debug Mailchimp requests before creating higher-level methods
  • Integrate bespoke flows that need custom headers, timeouts, or query params

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the saved Mailchimp connection/profile to use for authentication.

path ​

Type: String

Required: Yes

Relative API path (e.g., '/3.0/lists') or full URL ('https://<dc>.api.mailchimp.com/3.0/...').

method ​

Type: String

Required: Yes

HTTP method. One of: GET, POST, PUT, PATCH, DELETE.

data ​

Type: Object

Required: Yes

Request body object for POST/PUT/PATCH. For GET/DELETE, pass {}.

queryParams ​

Type: Object

Required: No

Query string parameters as an object (e.g., { count, offset, fields, exclude_fields }).

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config overrides (e.g., headers, timeout). Applies to this single call.

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: any }. On success, 'data' contains the Mailchimp API JSON response.

$io.mailchimp.getAudience ​

Fetch a single Mailchimp audience (list) by ID with optional field filtering.

Usage ​

js
$io.mailchimp.getAudience(connectionName, listId, fields, excludeFields, customRequestProperties)

Description ​

Retrieves one audience using Mailchimp Marketing API (GET /3.0/lists/{list_id}).

  • Field filtering: fields and exclude_fields reduce payload size. Accepts string (comma-separated) or array; arrays are joined with commas automatically.
  • Advanced per-call options (timeouts, headers, etc.) can be passed via customRequestProperties.

Usage Scenarios ​

  • Load details of a specific audience selected by a user
  • Display lightweight audience info by whitelisting just a few fields
  • Pre-flight checks before adding/updating members on a target audience

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

listId ​

Type: String

Required: Yes

The Mailchimp audience (list) ID to fetch.

fields ​

Type: String | Array<String>

Required: No

Whitelist of response fields (e.g., ['id','name','stats.member_count']).

excludeFields ​

Type: String | Array<String>

Required: No

Fields to exclude from the response (e.g., ['contact','campaign_defaults']).

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000 }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpListResponse }.

MailchimpListResponse mirrors the JSON returned by GET /3.0/lists/{list_id} and typically includes:

  • id: Audience ID
  • name: Audience name
  • contact: Organization contact info
  • campaign_defaults: From-name, from-email, subject, language
  • stats: Metrics such as member_count, unsubscribe_count, open_rate, click_rate
  • date_created: ISO timestamp the audience was created
  • list_rating: Integer quality score
  • email_type_option: Whether email type selection is enabled
  • subscribe_url_short / subscribe_url_long: Signup URLs

Example minimal response: { "id": "abcd1234", "name": "Main Newsletter", "stats": { "member_count": 1234, "open_rate": 0.25, "click_rate": 0.03 }, "date_created": "2025-06-01T10:15:00+00:00" }

$io.mailchimp.getCampaign ​

Fetch a single Mailchimp campaign by ID, with optional field trimming.

Usage ​

js
$io.mailchimp.getCampaign(connectionName, campaignId, fields, customRequestProperties)

Description ​

Retrieves a single campaign using Mailchimp Marketing API (GET /3.0/campaigns/{campaign_id}).

  • campaignId is required (the unique identifier of the campaign).
  • Optional fields lets you request only specific properties (string or array; arrays are joined with commas) to reduce payload.
  • Pass Axios options (e.g., timeouts/headers) via customRequestProperties.

Usage Scenarios ​

  • Load full details for a campaign selected from a list
  • Display subject, sender, and send metrics in a report view
  • Fetch a lightweight subset of fields for dashboards

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

campaignId ​

Type: String

Required: Yes

The Mailchimp campaign ID to fetch.

fields ​

Type: String | Array<String>

Required: No

Whitelist of response fields (e.g., ['id','status','type','send_time','emails_sent','settings.subject_line']).

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpCampaignResponse }.

MailchimpCampaignResponse mirrors JSON from GET /3.0/campaigns/{campaign_id} and commonly includes:

  • id: Campaign ID
  • status: 'save' (draft) | 'paused' | 'schedule' | 'sending' | 'sent'
  • type: 'regular' | 'plaintext' | 'rss' | 'variate'
  • send_time: ISO timestamp when the campaign was (or will be) sent
  • emails_sent: Number of emails sent (if applicable)
  • settings:

Example minimal response: { "id": "abc123", "status": "sent", "type": "regular", "send_time": "2025-07-15T16:00:00+00:00", "emails_sent": 12450, "settings": { "subject_line": "July Newsletter", "from_name": "Acme", "reply_to": "[email protected]" } }

$io.mailchimp.getMember ​

Fetch a single audience member by email (or subscriber_hash) within a specific Mailchimp list.

Usage ​

js
$io.mailchimp.getMember(connectionName, listId, emailOrHash, fields, customRequestProperties)

Description ​

Retrieves a single member using Mailchimp Marketing API (GET /3.0/lists/{list_id}/members/{subscriber_hash}).

  • listId is required because the same email may exist in multiple audiences.
  • emailOrHash can be a plain email (the function will MD5 hash trim(lowercase(email))) or a precomputed subscriber_hash.
  • Optional fields lets you request only specific properties to trim payload (string or array; arrays are joined with commas).
  • Advanced per-call options (timeouts, headers, etc.) can be passed via customRequestProperties.

Usage Scenarios ​

  • Look up a subscriber to show their current status and profile fields
  • Verify a contact before updating tags or merge fields
  • Load a lightweight member record for analytics or troubleshooting

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

listId ​

Type: String

Required: Yes

The Mailchimp audience (list) ID containing the member.

emailOrHash ​

Type: String

Required: Yes

Either the member's email address or their subscriber_hash (MD5 of trimmed, lowercased email).

fields ​

Type: String | Array<String>

Required: No

Whitelist of response fields (e.g., ['id','email_address','status','last_changed']).

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000 }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpMemberResponse }.

MailchimpMemberResponse mirrors JSON from GET /3.0/lists/{list_id}/members/{subscriber_hash} and typically includes:

  • id: Member ID (UUID)
  • email_address: The subscriber's email
  • status: 'subscribed' | 'unsubscribed' | 'cleaned' | 'pending' | 'transactional' | 'archived'
  • merge_fields: Object of custom fields (if present)
  • timestamp_opt: ISO timestamp when the member opted in (if applicable)
  • last_changed: ISO timestamp for the last update to this member

Example minimal response: { "id": "abc123", "email_address": "[email protected]", "status": "subscribed", "last_changed": "2025-07-20T12:34:56+00:00" }

$io.mailchimp.listAudiences ​

List Mailchimp audiences (lists) with optional field filtering and pagination.

Usage ​

js
$io.mailchimp.listAudiences(connectionName, count, offset, fields, excludeFields, customRequestProperties)

Description ​

Fetches audiences from the Mailchimp Marketing API (GET /3.0/lists) using the saved credentials in connectionName.

  • Pagination: controlled by count and offset.
  • Field filtering: fields and exclude_fields reduce payload size. You may pass either a string (comma-separated) or an array; arrays are joined with commas automatically.
  • Advanced per-call options (timeouts, headers, etc.) can be passed via customRequestProperties.

Use $io.mailchimp.nextOffsetFromTotal(total_items, prevOffset, count) to compute the next offset while paginating.

Usage Scenarios ​

  • Show all audiences to let a user pick a target list
  • Build dashboards of audience stats with minimal payload via fields/exclude_fields
  • Paginate through large accounts while keeping requests lightweight

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

count ​

Type: Number

Required: No

Maximum items to return. Default 100.

offset ​

Type: Number

Required: No

Number of items to skip (for pagination). Default 0.

fields ​

Type: String | Array<String>

Required: No

Whitelist of response fields (e.g., ['lists.id','lists.name','total_items']).

excludeFields ​

Type: String | Array<String>

Required: No

Fields to exclude from the response (e.g., ['lists._links','lists.stats']).

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000 }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpListsResponse }.

MailchimpListsResponse mirrors the JSON returned by GET /3.0/lists:

  • lists: Array of audience objects (each with id, name, contact info, campaign_defaults, stats, etc.)
  • total_items: Number of total audiences in the account

Example minimal response: { "lists": [ { "id": "abcd1234", "name": "Main Newsletter", "stats": { "member_count": 1234 } } ], "total_items": 1 }

$io.mailchimp.listCampaigns ​

List Mailchimp campaigns with pagination, optional filters, and field trimming.

Usage ​

js
$io.mailchimp.listCampaigns(connectionName, count, offset, filters, customRequestProperties)

Description ​

Fetches campaigns via Mailchimp Marketing API (`GET /3.0/campaigns`).

Controls:

  • Pagination: `count` (page size), `offset` (start index). Use `$io.mailchimp.nextOffsetFromTotal(total_items, prevOffset, count)` to iterate.
  • Filters (optional `filters` object; supported keys only):
    • `status`: e.g., 'sent', 'save' (draft), 'paused', 'schedule', 'sending'
    • `type`: e.g., 'regular', 'plaintext', 'rss', 'variate'
    • `since_create_time`, `before_create_time`: ISO timestamps to bound creation time
    • `since_send_time`, `before_send_time`: ISO timestamps to bound send time
    • `fields`, `exclude_fields`: string or array; arrays are joined with commas to trim payload
  • Field trimming: Request only the properties you need via `fields` (e.g., `['campaigns.id','campaigns.status','campaigns.type','total_items']`).
  • Advanced request options: Pass Axios options (timeouts, headers, etc.) via `customRequestProperties`.

Usage Scenarios ​

  • Build a dashboard of recent campaigns (sent/draft/scheduled)
  • Page through campaigns to pick one for reporting
  • Export a lightweight list of campaign metadata

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

count ​

Type: Number

Required: No

Maximum items per page. Default 50.

offset ​

Type: Number

Required: No

Number of items to skip (for pagination). Default 0.

filters ​

Type: Object

Required: No

Optional filter/field-trimming object. Supported keys: status, type, since_create_time, before_create_time, since_send_time, before_send_time, fields, exclude_fields.

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpListCampaignsResponse }.\n\nMailchimpListCampaignsResponse mirrors JSON from GET /3.0/campaigns and typically includes:\n- campaigns: Array of campaign objects (commonly fields like id, status, type, send_time, emails_sent, settings.subject_line, settings.from_name, settings.reply_to)\n- total_items: Number of campaigns matching the request\n\nExample minimal response:\n{\n "campaigns": [\n { "id": "abc123", "status": "sent", "type": "regular", "send_time": "2025-07-15T16:00:00+00:00", "emails_sent": 12450, "settings": { "subject_line": "July Newsletter" } }\n ],\n "total_items": 1\n}

$io.mailchimp.listMembers ​

List audience members (contacts) for a given Mailchimp list with filtering, sorting, field trimming, and pagination.

Usage ​

js
$io.mailchimp.listMembers(connectionName, listId, count, offset, opts, customRequestProperties)

Description ​

Fetches members from a specific audience using Mailchimp Marketing API (GET /3.0/lists/{list_id}/members).

Controls:

  • Pagination: count and offset.
  • Filters (via opts): status, since_last_changed, before_last_changed, since_timestamp_opt, before_timestamp_opt, email_type, sort_field (e.g., 'timestamp_opt', 'last_changed'), sort_dir ('ASC' | 'DESC').
  • Field trimming: opts.fields and opts.exclude_fields can be a string (comma-separated) or an array; arrays are joined with commas.
  • Advanced per-call options (timeouts, headers, etc.) can be passed via customRequestProperties.

Use $io.mailchimp.nextOffsetFromTotal(total_items, prevOffset, count) to drive pagination loops.

Usage Scenarios ​

  • Render a paginated table of subscribers for a selected audience
  • Export members updated within a date window
  • Fetch only lightweight fields for analytics or lookups

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

listId ​

Type: String

Required: Yes

The Mailchimp audience (list) ID to list members from.

count ​

Type: Number

Required: No

Maximum items to return per page. Default 50.

offset ​

Type: Number

Required: No

Number of items to skip (for pagination). Default 0.

opts ​

Type: Object

Required: No

Filter/sort/field options. Supported keys:

  • status
  • since_last_changed
  • before_last_changed
  • since_timestamp_opt
  • before_timestamp_opt
  • email_type
  • sort_field
  • sort_dir
  • fields
  • exclude_fields

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: {...} }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpMembersResponse }.

MailchimpMembersResponse mirrors JSON from GET /3.0/lists/{list_id}/members:

  • members: Array of member objects (commonly includes fields like id, email_address, status, timestamp_opt, last_changed, merge_fields, etc.)
  • total_items: Total number of members that match the request

Example minimal response: { "members": [ { "id": "abc123", "email_address": "[email protected]", "status": "subscribed" } ], "total_items": 1 }

$io.mailchimp.listReportClicks ​

List click performance for a campaign: either per-link stats or (optionally) the members who clicked a specific link.

Usage ​

js
$io.mailchimp.listReportClicks(connectionName, campaignId, count, offset, linkId, customRequestProperties)

Description ​

Retrieves click analytics for a campaign from the Mailchimp Marketing API.

Modes

  • Top-level link stats (default): GET /3.0/reports/{campaign_id}/click-details Returns an array of links with aggregate clicks (total/unique).
  • Per-link member drill-down (when linkId is provided): GET /3.0/reports/{campaign_id}/click-details/{link_id}/members Returns the members who clicked that link, including click counts and last-click timestamps.

Pagination

  • Use count (page size; commonly up to 1000) and offset.
  • Iterate with $io.mailchimp.nextOffsetFromTotal(total_items, prevOffset, count).

Advanced Options

  • Pass Axios options (timeouts, headers, etc.) via customRequestProperties.

Usage Scenarios ​

  • Identify the most-clicked links in a campaign
  • Drill down to which subscribers clicked a particular URL
  • Export clickers for retargeting workflows

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

campaignId ​

Type: String

Required: Yes

The Mailchimp campaign ID to report on.

count ​

Type: Number

Required: No

Maximum items per page. Default 1000.

offset ​

Type: Number

Required: No

Number of items to skip (for pagination). Default 0.

linkId ​

Type: String

Required: No

Optional link identifier. If provided, returns the members who clicked this link instead of top-level link stats.

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpReportClicksResponse }.

MailchimpReportClicksResponse (Top-level link stats): { "urls_clicked": [ { "id": 12345, "url": "https://example.com", "total_clicks": 87, "unique_clicks": 64 } ], "total_items": 1 }

MailchimpReportClicksResponse (Per-link member drill-down): { "members": [ { "email_address": "[email protected]", "clicks": 2, "last_click": "2025-07-20T12:34:56+00:00" } ], "total_items": 1 }

$io.mailchimp.listReportOpens ​

List member-level open details for a specific Mailchimp campaign (who opened, how many times), with pagination.

Usage ​

js
$io.mailchimp.listReportOpens(connectionName, campaignId, count, offset, customRequestProperties)

Description ​

Fetches open details via Mailchimp Marketing API (GET /3.0/reports/{campaign_id}/open-details).

  • campaignId is required.
  • Pagination: use count (page size, commonly up to 1000) and offset. Iterate with $io.mailchimp.nextOffsetFromTotal(total_items, prevOffset, count).
  • The response includes an array of member-level rows with open stats for the specified campaign.
  • Pass Axios options (timeouts/headers) via customRequestProperties.

Usage Scenarios ​

  • Analyze which subscribers opened a given campaign
  • Export openers for retargeting or follow-up
  • Build a report view with open counts and last-open timestamps

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

campaignId ​

Type: String

Required: Yes

The Mailchimp campaign ID whose openers you want to list.

count ​

Type: Number

Required: No

Maximum items per page (default 1000).

offset ​

Type: Number

Required: No

Number of items to skip (for pagination). Default 0.

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpReportOpenDetailsResponse }.

MailchimpReportOpenDetailsResponse typically includes:

  • members: Array<MemberOpenRow>
  • total_items: Number
  • (optionally) campaign_id, campaign_title

MemberOpenRow commonly includes:

  • email_address: Subscriber email
  • opens_count: Total number of opens for this campaign
  • last_open: ISO timestamp of the most recent open (if present)
  • list_id: Audience ID the member belongs to
  • merge_fields, email_id, id, and other Mailchimp-specific attributes may also be present

Example minimal response: { "members": [ { "email_address": "[email protected]", "opens_count": 3, "last_open": "2025-07-20T12:34:56+00:00", "list_id": "abcd1234" } ], "total_items": 1 }

$io.mailchimp.nextOffsetFromTotal ​

Compute the next offset for Mailchimp list-style pagination using total_items.

Usage ​

js
$io.mailchimp.nextOffsetFromTotal(totalItems, prevOffset, count)

Description ​

Mailchimp endpoints commonly paginate with count and offset.

This helper computes the next offset and indicates if more pages exist.

  • If the next offset would exceed or equal total_items, it returns { nextOffset: null, hasMore: false }.
  • Otherwise, it returns { nextOffset: prevOffset + count, hasMore: true }.

Use this in a loop until hasMore is false.

Usage Scenarios ​

  • Paginate through all audiences (lists) in Mailchimp
  • Loop through members of a large audience
  • Stop fetching once all results have been retrieved

Parameters ​

totalItems ​

Type: Number

Required: Yes

The total number of items available (from Mailchimp's 'total_items').

prevOffset ​

Type: Number

Required: Yes

The current offset you used in the last call.

count ​

Type: Number

Required: Yes

The page size used in the last call (same as the 'count' parameter).

Output ​

Type: Object

An object { nextOffset: Number|null, hasMore: Boolean }.

  • nextOffset: the new offset to use for the next page, or null if finished.
  • hasMore: true if another page exists, false if done.

$io.mailchimp.removeTagsFromMember ​

Remove (deactivate) one or more tags from a member in a specific Mailchimp audience.

Usage ​

js
$io.mailchimp.removeTagsFromMember(connectionName, listId, emailOrHash, tags, customRequestProperties)

Description ​

Deactivates tags on a member via Mailchimp Marketing API (POST /3.0/lists/{list_id}/members/{subscriber_hash}/tags).

  • emailOrHash can be a plain email (normalized + MD5 hashed internally) or a precomputed subscriber_hash.
  • tags must be a non-empty array of strings. Each tag is sent as { name: <tag>, status: 'inactive' }.
  • Calling this for a tag that's already inactive/nonexistent is effectively idempotent (no-op success).
  • Advanced per-call options (timeouts, headers, etc.) can be passed via customRequestProperties.

To confirm current tags, read back with GET /3.0/lists/{list_id}/members/{subscriber_hash}/tags.

Usage Scenarios ​

  • Unflag contacts after a lifecycle step is completed
  • Clean up temporary campaign tags
  • Reverse tagging applied by automations or bulk imports

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

listId ​

Type: String

Required: Yes

Target audience (list) ID.

emailOrHash ​

Type: String

Required: Yes

Member identifier: email address or subscriber_hash (MD5 of trimmed, lowercased email).

tags ​

Type: Array<String>

Required: Yes

Non-empty array of tag names to deactivate for the member.

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: null } on success. Note: Mailchimp typically returns 204 No Content for this endpoint, so data is usually null. Use a follow-up GET to the member's /tags endpoint to verify.

$io.mailchimp.searchMembers ​

Search Mailchimp contacts by email or name, optionally scoped to a specific audience (list).

Usage ​

js
$io.mailchimp.searchMembers(connectionName, query, listId, count, offset, customRequestProperties)

Description ​

Calls Mailchimp Marketing API (GET /3.0/search-members) to search for contacts.

  • query: free text; commonly a full email (exact), partial email, or a name (e.g., "Ada Lovelace").
  • listId (optional): scope the search to one audience for faster, more precise results.
  • Pagination via count and offset. Use $io.mailchimp.nextOffsetFromTotal(...) if the response includes totals.
  • Archived contacts are not returned by this endpoint (it searches current list members).
  • For domain-style lookups, prefer scoping to a list and/or paging listMembers then filtering client-side.

Usage Scenarios ​

  • Find which audience a given email belongs to
  • Lookup a contact by first/last name before performing updates
  • Drive a picker UI that narrows results as the user types

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

query ​

Type: String

Required: Yes

Search text (email, partial email, first/last name).

listId ​

Type: String

Required: No

Optional audience (list) ID to restrict the search.

count ​

Type: Number

Required: No

Maximum items to return per page. Default 50.

offset ​

Type: Number

Required: No

Number of items to skip (for pagination). Default 0.

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpSearchMembersResponse }.

MailchimpSearchMembersResponse:

  • exact_matches: { members: Array<Member>, total_items: Number } — present when the query is an exact email.
  • full_search: { members: Array<Member>, total_items: Number } — broader matches (partial email/name).

Each Member object mirrors Mailchimp's member shape (commonly includes: list_id, id, email_address, status, merge_fields, last_changed).

Example minimal response: { "exact_matches": { "members": [ { "list_id": "abcd1234", "email_address": "[email protected]", "status": "subscribed" } ], "total_items": 1 }, "full_search": { "members": [ { "list_id": "abcd1234", "email_address": "[email protected]" } ], "total_items": 7 } }

$io.mailchimp.subscriberHash ​

Compute the Mailchimp subscriber_hash (MD5 hex of the lowercase, trimmed email).

Usage ​

js
$io.mailchimp.subscriberHash(email)

Description ​

Returns the subscriber_hash that Mailchimp expects in many member endpoints.

Algorithm:

  1. Coerce to string
  2. Trim whitespace
  3. Lowercase
  4. MD5 digest → hex string (32 chars)

Example:

Use this value in paths like: /3.0/lists/{list_id}/members/{subscriber_hash}

Usage Scenarios ​

  • Build member endpoints that require subscriber_hash in the URL
  • Upsert a member via PUT /lists/{list_id}/members/
  • Fetch/update/delete a specific member without first searching by email

Parameters ​

email ​

Type: String

Required: Yes

Email address to hash. Will be trimmed and lowercased before hashing.

Output ​

Type: String

32-character lowercase hex MD5 digest of the normalized email.

$io.mailchimp.updateMember ​

PATCH an existing audience member in a Mailchimp list by email or subscriber_hash (partial update of fields).

Usage ​

js
$io.mailchimp.updateMember(connectionName, listId, emailOrHash, fields, customRequestProperties)

Description ​

Performs a partial update of a member using Mailchimp Marketing API (PATCH /3.0/lists/{list_id}/members/{subscriber_hash}).

  • listId is required (members are scoped to an audience).
  • emailOrHash can be a plain email (normalized + MD5 inside) or a precomputed subscriber_hash.
  • fields is an object of attributes to change (e.g., { merge_fields: { FNAME: 'Ada' }, language: 'en', status: 'unsubscribed' }).
  • Use PATCH for targeted changes; use PUT (createOrUpdateMember) to upsert the full record.
  • Tags are managed via dedicated endpoints (addTagsToMember / removeTagsFromMember).
  • Advanced per-call options (timeouts, headers, etc.) can be passed via customRequestProperties.

Usage Scenarios ​

  • Update merge fields (e.g., first/last name) for an existing subscriber
  • Change a member’s status (e.g., unsubscribe)
  • Adjust profile attributes like language or VIP without replacing the whole record

Parameters ​

connectionName ​

Type: String

Required: Yes

Name of the configured Mailchimp connection/profile.

listId ​

Type: String

Required: Yes

The Mailchimp audience (list) ID that contains the member.

emailOrHash ​

Type: String

Required: Yes

Member identifier: either the email address or the subscriber_hash (MD5 of trimmed, lowercased email).

fields ​

Type: Object

Required: Yes

Object of fields to patch (e.g., { merge_fields: {...}, language: 'en', status: 'unsubscribed', vip: false }).

customRequestProperties ​

Type: Object

Required: No

Advanced Axios config for this call (e.g., { timeout: 8000, headers: { ... } }).

Output ​

Type: Promise

Resolves to { status: boolean, err: string|null, data: MailchimpMemberResponse }.

MailchimpMemberResponse mirrors JSON from PATCH /3.0/lists/{list_id}/members/{subscriber_hash} and typically includes:

  • id: Member ID (UUID)
  • email_address: The subscriber's email
  • status: Current subscription status
  • merge_fields: Custom fields (if present)
  • language: Preferred language (if set)
  • last_changed: ISO timestamp of the last update

Example minimal response: { "id": "abc123", "email_address": "[email protected]", "status": "unsubscribed", "merge_fields": { "FNAME": "Ada", "LNAME": "Lovelace" }, "last_changed": "2025-07-20T12:34:56+00:00" }