Mailchimp Audiences UpsertMember

Mailchimp Audiences UpsertMember
Certified
Add or update a member of a Mailchimp audience

Creates the member if it does not exist, otherwise updates it, with PUT /lists/{listId}/members/{subscriberHash}. The hash is the MD5 of the trimmed, lower-cased email, so the same address always targets the same member. Calling it again with the same input is safe.

statusIfNew is required and only applies when the member is created; status also changes an existing member. Optional fields you leave unset are not sent, so existing values are kept.

Only add contacts who have opted in; you are responsible for GDPR and Mailchimp terms.

yaml
type: io.kestra.plugin.mailchimp.audiences.UpsertMember

Examples

Subscribe a contact to an audience, or update them if they already exist.

yaml
id: mailchimp_upsert_member
namespace: company.team

tasks:
  - id: upsert
    type: io.kestra.plugin.mailchimp.audiences.UpsertMember
    apiKey: "{{ secret('MAILCHIMP_API_KEY') }}"
    listId: "a1b2c3d4e5"
    email: "jane.doe@example.com"
    statusIfNew: SUBSCRIBED
    mergeFields:
      FNAME: Jane
      LNAME: Doe
    tags:
      - newsletter

Properties

email *string

Email address

Contact email. Trimmed and sent as given; only the subscriber hash uses the lower-cased form.

listId *string

Audience ID

Mailchimp audience (list) id, found in the audience settings or with ListAudiences.

statusIfNew *string

Possible Values

SUBSCRIBEDUNSUBSCRIBEDCLEANEDPENDINGTRANSACTIONAL

Status if new

Status given when the member does not exist yet: SUBSCRIBED, UNSUBSCRIBED, CLEANED, PENDING or TRANSACTIONAL. PENDING sends a double opt-in email.

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.

Definitions

io.kestra.core.models.assets.AssetsDeclaration

assetFailureBehaviorstring

Possible Values

IGNOREFAILWARN

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

enableAutobooleanstring

Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.

inputsarray

The assets consumed as inputs.

io.kestra.core.models.assets.AssetIdentifier

id*string

Min length1

typestring

outputs

The assets produced as outputs.

io.kestra.plugin.ee.assets.Dataset

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.File

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.Table

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.VM

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.External

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.Custom

id*string

Min length1

Max length150

type*string

Min length1

Custom asset type

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

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

language string

Language

Subscriber language code such as en or fr.

maxRetries integerstring

Default3

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

mergeFields object

Merge fields

Merge field values by tag, e.g. FNAME: Jane.

server string

Data center

Mailchimp data center such as us19. Required with accessToken, optional with apiKey (overrides the key suffix).

skipMergeValidation booleanstring

Skip merge validation

Accept the member even when required merge fields are missing (skip_merge_validation).

status string

Possible Values

SUBSCRIBEDUNSUBSCRIBEDCLEANEDPENDINGTRANSACTIONAL

Status

New status for the member, also applied to an existing member: SUBSCRIBED, UNSUBSCRIBED, CLEANED, PENDING or TRANSACTIONAL. Not sent when unset.