Mailchimp: Telltide Seed Address Guide

Mailchimp's core constraint for seeds is contact status: a contact must be subscribed to receive marketing emails. Unsubscribed and cleaned contacts cannot be re-subscribed programmatically, only via a contact re-subscribing themselves through a form, or via the Resubscribe button in the UI. Plan around this: seed addresses should never be used in any other capacity that might trigger an unsubscribe, and should be carefully protected from bounce or spam classification.

Quick reference

---

1. Scheduled / one-off sends (Campaigns)

Mailchimp Campaigns are one-time or scheduled sends to a defined portion of an Audience. Seeds must be subscribed members of the target Audience and must match any segment or tag filters applied to the campaign.

Where to add seed addresses

Add the seed contact to the Audience used in the campaign. Then ensure the seed is in any tag, group, or segment the campaign targets.

Non-technical path

For CRM managers working in the Mailchimp web app. Three options: add a single contact via the Audience UI, bulk-import via CSV, or have the seed sign up through your hosted form.

Option A: Add a single contact via the Audience UI

1. Navigate to Audience > All contacts (confirm the correct audience is selected in the Audience dropdown)
2. Click Add contacts > Add a subscribed contact (in some tenants this is labelled "Add a single contact")
3. Enter the seed email address
4. Add first name, last name, and any merge field values needed for personalization
5. Check "This person gave me permission to email them" to set status to subscribed
6. Apply any tags that the campaign targets
7. If using groups: check the appropriate group options
8. Click Add contact

Option B: Add a seed contact via CSV import

1. Navigate to Audience > All contacts > Add contacts > Import contacts
2. Select "Upload a CSV or tab-delimited text file"
3. Download the template or use your own CSV with columns: Email Address, First Name, Last Name, plus any merge tag columns (e.g., BIRTHDAY)
4. Set the Status column value to subscribed for the seed row
5. Upload the file and map columns
6. On the import settings step: check "Update any existing contacts" if the seed already exists in the audience and you want to refresh its data (without this, existing records are skipped silently)
7. Apply any tags to imported contacts if needed
8. Confirm the import

Option C: Embedded signup form

1. Find the Audience's hosted signup form URL under Audience > Signup forms
2. Submit the seed email address through the form
3. Apply any tags or group memberships afterward via Audience > All contacts

Technical path

For developers using the Mailchimp Marketing API.

Compute the subscriber hash: MD5 of the contact's email address, lowercased. The API uses this hash as the contact identifier.

Create or update a contact (upsert by email):

PUT /3.0/lists/{list_id}/members/{subscriber_hash}
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "email_address": "seed@example.com",
  "status_if_new": "subscribed",
  "merge_fields": {
    "FNAME": "Seed",
    "LNAME": "Monitor"
  }
}

status_if_new: "subscribed" sets status only for new contacts. Use status: "subscribed" with caution (risk of re-subscribing previously-unsubscribed contacts is blocked, but prefer the upsert form).

Apply a tag to the seed:

POST /3.0/lists/{list_id}/members/{subscriber_hash}/tags
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "tags": [{"name": "telltide-seed", "status": "active"}]
}

Curl example with HTTP Basic auth:

curl --user "anystring:YOUR_API_KEY" \
  -X PUT "https://{dc}.api.mailchimp.com/3.0/lists/{list_id}/members/{subscriber_hash}" \
  -H "Content-Type: application/json" \
  -d '{"email_address":"seed@example.com","status_if_new":"subscribed"}'

For bulk seed setup across many audiences, use the Batch endpoint (POST /batches) to bundle up to 1,000 member operations per request.

Always-on flow coverage

Adding the seed once to an audience is not enough. To guarantee coverage across every recurring campaign and every Customer Journey entry event, ensure the seed satisfies the entry condition for each.

Recurring campaigns (segments and tags):

• If a campaign targets a segment, add the seed's tag (e.g., telltide-seed) as an OR clause in the segment's conditions. This guarantees the seed is included regardless of the segment's other filters.
• If a campaign targets a tag directly, apply that tag to the seed.
• If a campaign targets the entire audience, no extra step is needed beyond subscribed status.
• Check the campaign's Don't send to exclusion list (up to 10 advanced or regular segments/tags, or 1 legacy segment). The seed must not appear in any excluded segment or tag.

Customer Journey entry events:

• For "Tag added" starting points: ensure the seed receives the trigger tag whenever a real contact would. If the trigger tag is applied by an automation, integration, or manual workflow, verify that workflow fires for the seed too. For testing, you can apply the tag manually via Audience > Tags or via the API.
• For "Signs up for email" starting points: confirm the "Include imported contacts" toggle matches your seed-add method. If you add seeds via CSV or API, the toggle must be on; otherwise the seed will not enter the journey.
• For "Event API" starting points: fire the same event payload for the seed that real contacts would trigger. The event name must match the journey's configured event name exactly.
• For e-commerce starting points (Order confirmation, Abandoned cart, Abandoned browse): the seed must perform the underlying store action under the same email. There is no shortcut.
• For segment-based or behavioural starting points: add the seed's tag as an OR clause in the journey's entry segment, mirroring the campaign approach above.
• Check the journey's re-entry settings. By default Mailchimp blocks re-entry for ~5 minutes after exit, and re-entry can be disabled entirely. For repeated seed testing, enable re-entry and shorten the cooldown.

Audit checklist before going live:

1. Seed is subscribed in every audience used by monitored campaigns and journeys.
2. Seed carries the telltide-seed tag (or your chosen tag), and that tag is OR'd into every segment used as a campaign filter or journey entry.
3. Seed is not present in any Don't send to exclusion segment or tag.
4. For each journey, the entry trigger fires for the seed (verified via test send or trigger log).
5. For tag-triggered journeys, re-entry is enabled if you need repeatable testing.

Profile attributes required

Seeds need:

• Email Address (required)
• subscribed status
• Merge field values for any personalization tokens in the email (FNAME, LNAME, etc.)
• Group or tag membership matching the campaign's targeting

Seeds do not need demographic matching criteria unless the campaign is targeted to a segment with demographic filters.

Ensuring seeds receive the same version as real recipients

A/B tests: Mailchimp randomly assigns contacts (including seeds) to test variants. The seed will receive one variant - not all. To confirm all variants are delivered, you need one seed per variant, or run separate test sends after determining which variant each contact received.

Campaign exclusions: Check the Don't send to section of the campaign's Recipients step to verify the seed is not in any excluded list or segment.

Gotchas

Cleaned contacts cannot receive email: If a seed address hard-bounced in this audience, it will be marked as cleaned and cannot receive future sends in that audience. Cleaned status is per-audience, but the underlying email is still invalid, so reusing it in another audience will likely cleanse again. Use a fresh seed address.

Unsubscribed contacts cannot be re-subscribed via API: If a seed contact's status is unsubscribed, you cannot change it via API. Use the UI Resubscribe button (Audience > Contacts > find contact > Resubscribe) or create a new seed contact.

One email address per audience: Mailchimp enforces one record per email per audience. If you submit the same email twice with different data, Mailchimp updates the existing record.

Frequency: Campaign sends have no inherent frequency cap. However, Customer Journeys have configurable re-entry cooldowns and exclusion settings that can silently prevent a seed from re-entering. When testing repeated triggers on the same seed, check the journey's re-entry settings.

---

2. Ongoing / automated journeys (Marketing Automation Flows)

Mailchimp's Customer Journey Builder (also called Marketing Automation Flows) handles all automated email sequences. Classic Automations were retired on June 1, 2025. All new automation work uses the Journey Builder. Note that the Free plan no longer supports Marketing Automation Flows or Customer Journeys as of June 2025; a paid plan is required for any automated journey work, including seed monitoring on automated flows.

Each Journey can have up to 3 starting point triggers. Seeds must satisfy one of the configured starting points.

Creating trap profiles per journey type

Welcome / onboarding

• Starting point: "Signs up for email" (contact joins the Audience via signup form) or "Tag added" (a specific tag is applied to the contact)
• Seed requirements: Email address, subscribed status in the target Audience
• How to trigger (Tag-based): 1. Ensure the Journey uses the "Tag added" starting point for a specific tag (e.g., "welcome-trigger") 2. Add the seed contact to the Audience (if not already present) 3. Apply the trigger tag to the seed:
• UI: Audience > Tags, then open the tag and use Bulk tag or apply via the contact list
• API: POST /3.0/lists/{list_id}/members/{hash}/tags with {"tags": [{"name": "welcome-trigger", "status": "active"}]} 4. The Journey fires automatically when the tag is applied
• How to trigger (Form-based): The "Signs up for email" trigger fires when a contact joins the audience as subscribed, including via API. By default, the trigger may exclude imported contacts; check the "Include imported contacts" option in the starting point settings if you want CSV/API additions to count. Options:
• Submit the seed email address through the actual hosted signup form for the Audience
• Enable "Include imported contacts" on the starting point and add the seed via CSV or API
• Use the "Tag added" starting point instead (most reliably testable)
• Gotcha: Existing audience members at the time of journey publication do not auto-enter. New signups after publication do enter. The "Include imported contacts" toggle in the trigger's settings controls whether CSV/API-imported contacts count as signups. You can also manually add contacts to an active flow via Edit > add to flow.

Abandoned cart

• Starting point: "Abandons cart"
• Required setup: An e-commerce store must be connected to Mailchimp (Shopify, WooCommerce, BigCommerce, or Mailchimp E-commerce API)
• Seed requirements: Email address, subscribed status, the seed must be an identified shopper on the connected store
• How cart abandonment is detected: When a shopper adds items to their cart on the connected store, the integration syncs cart data. If the shopper doesn't complete purchase within the configured wait window, the Journey trigger fires.
• For seed testing: 1. Connect the seed email address to a shopping session in your store (log in with an account using the seed address, or proceed to checkout and enter the seed email) 2. Add items to the cart 3. Abandon the checkout (close the browser/navigate away) 4. Wait for the configured abandonment window (e.g., 1 hour) 5. The Journey fires and sends the abandoned cart email to the seed address
• Email content: Mailchimp auto-inserts a Cart content block showing the abandoned items. This data is pulled from the store integration.
• Gotcha: The seed contact must be subscribed status. Non-subscribed contacts whose cart data is tracked are excluded from the automation.

[NEEDS VERIFICATION: exact abandonment detection window configuration options in current Journey Builder UI]

Browse abandonment

• Starting point: Mailchimp has a native "Abandoned browse" / "Views pages in Shopify store" trigger but only for Shopify-connected stores. For other store integrations or no store, use the Event API approach.
• Options:
• Use a Shopify-connected store with the "Abandoned browse" or "Views pages in Shopify store" trigger
• Use a connected e-commerce store with product tracking (requires the store integration to track individual product views)
• Use the Events API to fire a custom event against the contact, then configure an "Event API" starting point in the Journey Builder (Standard plan or higher is required for multi-step flows; Essential can use Event API to trigger a single-email Customer Journey)
• Events API approach:

POST /3.0/lists/{list_id}/members/{subscriber_hash}/events
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "name": "product_viewed",
  "properties": {
    "product_name": "Widget Pro",
    "product_category": "Electronics",
    "product_url": "https://yourstore.com/products/widget-pro",
    "price": 49.99
  }
}

Then configure the Journey's starting point to "Event API" and filter on event name product_viewed.

Plan availability: Standard plan or higher is required to create multi-step flows with an Event API trigger. Essential can use Event API to trigger a single-email Customer Journey but not multi-step flows. The Free plan does not support Customer Journeys at all.

Winback / re-engagement

• Starting point: "Customer churn risk" (Mailchimp's predictive analytics assigns churn risk level) or a date-based trigger on the last purchase date
• For churn-risk trigger:
• Mailchimp's predictive analytics assigns High, Medium, or Low churn risk based on engagement and purchase history
• Seeds have no purchase history and limited engagement history, so they may not get a predictive churn risk score
• Workaround: Use a tag-based starting point ("Tag added") with a manually-applied churn-risk-test tag, since seeds will not have predictive scores. The "Time until predicted purchase" trigger also requires purchase history, so it is not a viable fallback for fresh seeds.
• Segment-based approach: 1. Create a segment: "Email campaign activity > Has not opened in the last 90 days" 2. Create a Journey with an appropriate date-based trigger 3. Add the seed to the Audience and ensure they have no recent email opens recorded (a fresh seed with no open history qualifies automatically)

Post-purchase

• Starting point: "Order confirmation" (with optional segment filter for first-time customers; requires connected store). "First purchase" was a Classic Automation type, not a current Journey starting point name.
• Seed requirements: Email address, subscribed status, the seed must have a purchase event on the connected store
• How to trigger: 1. Use the seed email address to complete an actual purchase in your connected store 2. The store integration syncs the order to Mailchimp 3. The Journey trigger fires
• Email content: Product recommendation blocks use historical purchase data. A seed with one test purchase may not generate useful recommendations.

Birthday

• Starting point: "Birthday"
• Required merge field: BIRTHDAY - must be a Birthday-type field in the Audience (not a generic Date field)
• Format: MM/DD (month/day only - no year)

Step-by-step: Add Birthday merge field to Audience

1. Navigate to **Audience > All contacts > Settings > Audience fields and *|MERGE|* tags** (or via the More options drop-down > Audience fields and merge tags > Edit audience fields)
2. Click Create a new field
3. Select type Birthday
4. Set the merge tag (default: BIRTHDAY)
5. Click Save Changes

Setting the birthday on a seed contact:

• UI: Open the seed contact record > find the BIRTHDAY merge field > enter MM/DD
• CSV import: Include a BIRTHDAY column with MM/DD values
• API: Include BIRTHDAY in the merge_fields object:

PUT /3.0/lists/{list_id}/members/{subscriber_hash}
{
  "merge_fields": {
    "BIRTHDAY": "04/15"
  }
}

Gotcha: A regular Date merge field (not Birthday type) will NOT trigger the Birthday starting point. The field must be specifically set to type "Birthday" in the Audience field settings. You cannot retroactively change a Date field to a Birthday field - you must create a new Birthday-type field.

When the trigger fires: Annually on the contact's birth date (month/day match). You can configure the Journey to trigger X days before the birthday.

---

Where to create seed profiles in the Mailchimp UI

1. Audience > All contacts > Add contacts > Add a subscribed contact for manually adding a single seed
2. Audience > All contacts > Add contacts > Import contacts for bulk import with merge field data
3. Audience > Tags for applying tags to existing contacts to trigger tag-based Journeys
4. **Audience > All contacts > Settings > Audience fields and *|MERGE|* tags** for managing merge field setup required for date triggers

Ensuring seeds progress through the full Journey

Wait steps: Journeys use Wait steps between emails. Seeds must remain in the Audience as subscribed contacts for the duration of the Journey (which may span weeks).

If/else branches: Some Journeys route contacts based on conditions (opened previous email, clicked a link, made a purchase). Confirm which branch you want the seed to take and plan interactions accordingly.

Journey API trigger (to force-add a contact to a specific Journey step):

POST /customer-journeys/journeys/{journey_id}/steps/{step_id}/actions/trigger
{
  "email_address": "seed@example.com"
}

This endpoint manually triggers a specific step in a Journey for a contact. Use it to force the seed into any Journey step without waiting for the triggering condition. Requires knowing the journey_id and step_id (retrieve via the API).

---

How to reset seeds for repeated Journey testing

Tag-based trigger: Remove the trigger tag from the seed contact, then re-add it. This re-fires the "Tag added" starting point.

API event trigger: Fire the triggering API event again for the seed contact.

Form subscription trigger: Cannot be re-triggered after the first subscription without the contact re-subscribing. Use the tag-based approach instead for repeatable testing.

Create a new seed contact: Use a new seed email address (or a + variant of your seed inbox address if your mail server supports it). The new contact has no history and can enter Journeys fresh.

---

3. Platform-specific considerations

API options

Create or update contact (upsert by email):

PUT /3.0/lists/{list_id}/members/{md5_lowercase_email_hash}

status_if_new: "subscribed" sets status only for new contacts; use status: "subscribed" with caution (risk of re-subscribing unsubscribed contacts).

Add/remove tags:

POST /3.0/lists/{list_id}/members/{hash}/tags
{
  "tags": [{"name": "tag-name", "status": "active"}]
}

Fire a custom event:

POST /3.0/lists/{list_id}/members/{hash}/events

Trigger a Journey step for a contact:

POST /customer-journeys/journeys/{journey_id}/steps/{step_id}/actions/trigger

API base URL: https://{dc}.api.mailchimp.com/3.0/ where {dc} is your server prefix (e.g., us6)

Authentication: HTTP Basic Auth (any username, API key as password) OR Authorization: Bearer {api_key}.

Computing subscriber hash: MD5 hash of the contact's email address lowercased. Most HTTP clients have MD5 functions. Example: MD5("urist.mcvankab+1@freddiesjokes.com") = 62eeb292278cc15f5817cb78f7790b08

Rate limits

For bulk contact operations, use the Batch endpoint (POST /batches) to bundle up to 1,000 member operations per request.

Duplicate contact handling

Mailchimp automatically deduplicates within a single Audience - the same email can only exist once per Audience. If you submit an existing email via import or API, the existing record is updated rather than duplicated.

The same email CAN exist in multiple Audiences with different statuses. If a contact is subscribed in Audience A and unsubscribed in Audience B, they receive emails sent to Audience A.

Mailchimp recommends using a single Audience with tags and segments for contact management rather than multiple Audiences, to avoid billing for the same contact multiple times.

Platform-specific terminology

Known limitations and workarounds

Classic Automations are retired: Any documentation or tutorials referencing Classic Automations are outdated. Use the Customer Journey Builder exclusively.

Abandoned cart and post-purchase require a connected e-commerce store: These Journey triggers cannot be used without an active store integration. There is no generic event-based alternative for these specific triggers.

Unsubscribed contacts cannot be re-subscribed via API: This is a deliberate compliance protection. Plan seed addresses to never unsubscribe, and never test unsubscribe workflows with seed addresses you need for monitoring.

Birthday field must be a Birthday-type field, not a Date type: Creating the wrong field type is an easy mistake. Check Audience > All contacts > Settings > Audience fields and *|MERGE|* tags to confirm the BIRTHDAY field is type "Birthday" before setting values on contacts.

"Signs up for email" trigger has an "Include imported contacts" toggle: By default the trigger may exclude CSV/API-added contacts. If you add seeds programmatically, enable this toggle in the starting point settings. For maximum repeatability, prefer the "Tag added" starting point.