Mailchimp Audiences BatchSubscribe
CertifiedSubscribe or update many members of a Mailchimp audience
Mailchimp Audiences BatchSubscribe
Subscribe or update many members of a Mailchimp audience
Reads an ION file from internal storage row by row and sends the members to POST /lists/{listId} in chunks of chunkSize (500 at most, Mailchimp's limit), one request after the other. The file is streamed, never loaded in memory.
Each row needs emailAddress and status (subscribed, unsubscribed, cleaned, pending or transactional), and may have mergeFields (object) and tags (list of names). The whole file is checked before the first request, so a bad row fails the task before anything is sent and the message names the 1-based row number.
Mailchimp answers 200 even when some members were rejected; those are reported in errors. By default (failOnError: true) the task fails after all chunks were sent if any member was rejected. A failed request (for example a 5xx) fails the task at once and is never retried, because replaying a POST could repeat work; the message tells how many chunks had already succeeded so you can resume. Retries only apply to 429. An empty file makes no request.
Only add contacts who have opted in; you are responsible for GDPR and Mailchimp terms.
type: io.kestra.plugin.mailchimp.audiences.BatchSubscribeExamples
Subscribe a list of members.
id: mailchimp_batch_subscribe
namespace: company.team
tasks:
- id: subscribe
type: io.kestra.plugin.mailchimp.audiences.BatchSubscribe
apiKey: "{{ secret('MAILCHIMP_API_KEY') }}"
listId: "a1b2c3d4e5"
from:
- emailAddress: jane.doe@example.com
status: subscribed
mergeFields:
FNAME: Jane
tags:
- newsletter
- emailAddress: john.doe@example.com
status: pending
updateExisting: true
failOnError: false
Subscribe the rows of an ION file, here the members of another audience.
id: mailchimp_copy_audience
namespace: company.team
tasks:
- id: members
type: io.kestra.plugin.mailchimp.audiences.ListMembers
apiKey: "{{ secret('MAILCHIMP_API_KEY') }}"
listId: "a1b2c3d4e5"
status: SUBSCRIBED
fetchType: STORE
- id: subscribe
type: io.kestra.plugin.mailchimp.audiences.BatchSubscribe
apiKey: "{{ secret('MAILCHIMP_API_KEY') }}"
listId: "f6g7h8i9j0"
from: "{{ outputs.members.uri }}"
Properties
from *stringarrayobject
Members to subscribe
Structured data items can be defined in the following ways:
- A single item as a map (a document).
- A list of items as a list of maps (a list of documents).
- A URI, supported schemes are
kestrafor internal storage files,filefor host local files, andnsfilefor namespace files. - A JSON String that will then be serialized either as a single item or a list of items. Each item is one member with
emailAddressandstatus, and optionallymergeFieldsandtags.
Pebble expression referencing an Internal Storage URI e.g. {{ outputs.mytask.uri }}.
listId *string
Audience ID
Mailchimp audience (list) id, found in the audience settings or with ListAudiences.
accessToken string
OAuth access token
Set exactly one of apiKey or accessToken. server is required with an access token.
apiKey string
Mailchimp API key
Set exactly one of apiKey or accessToken. The data center is taken from the key suffix (for example -us19) unless server is set.
assets
Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.
io.kestra.core.models.assets.AssetsDeclaration
IGNOREFAILWARNAsset failure behavior
Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.
Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.
The assets consumed as inputs.
io.kestra.core.models.assets.AssetIdentifier
1The assets produced as outputs.
io.kestra.plugin.ee.assets.Dataset
1150{}1150io.kestra.plugin.ee.assets.File
1150{}1150io.kestra.plugin.ee.assets.Table
1150{}1150io.kestra.plugin.ee.assets.VM
1150{}1150io.kestra.core.models.assets.External
1150{}1150io.kestra.core.models.assets.Custom
11501Custom asset type
{}1150baseUrl string
Base URL override
Replaces https://<server>.api.mailchimp.com/3.0. The credential is sent to this URL, so it must be an https *.api.mailchimp.com host.
chunkSize integerstring
500Chunk size
Members per request, between 1 and 500. Default 500.
failOnError booleanstring
trueFail on error
Fail the task, after all chunks were sent, when Mailchimp rejected members. When false, they are returned in errors. Default true.
maxRetries integerstring
3Max retries
Retries done by this plugin on HTTP 429 (all methods) and on 5xx or I/O errors (GET and PUT only), with exponential backoff. Default 3, between 0 and 10. Kestra's HTTP client also replays a GET or PUT once after a 429 or 503 on its own, so 0 only turns off the plugin's retries.
server string
Data center
Mailchimp data center such as us19. Required with accessToken, optional with apiKey (overrides the key suffix).
skipDuplicateCheck booleanstring
Skip duplicate check
Do not check the batch for duplicate emails (skip_duplicate_check).
skipMergeValidation booleanstring
Skip merge validation
Accept members with missing required merge fields (skip_merge_validation).
syncTags booleanstring
Sync tags
Replace the tags of existing members by the ones in the file (sync_tags).
timeout string
PT2MRequest timeout
Idle read timeout of each call: how long to wait without receiving data. Default PT2M, must be positive. Mailchimp itself cuts requests off after 120 seconds.
updateExisting booleanstring
Update existing
Update members that already exist (update_existing). Mailchimp's default is false: existing members are then reported as errors.
Outputs
batches integer
0Batches
Number of HTTP requests sent.
errorCount integer
0Error count
Members rejected by Mailchimp (error_count), summed over all requests.
errors array
Errors
Rejected members with Mailchimp's message and code, capped at 1000 entries. Mailchimp may list fewer than errorCount; errorCount is always the full total.
io.kestra.plugin.mailchimp.audiences.BatchSubscribe-Output-MemberError
Email address
Email of the rejected member.
Error
Mailchimp's message.
Error code
Mailchimp's error code, e.g. ERROR_CONTACT_EXISTS.
totalCreated integer
0Created
Members created, summed over all requests.
totalUpdated integer
0Updated
Members updated, summed over all requests.
