Mailchimp

Overview

Mailchimp is a platform used for creating and sending mass emails. The Mailchimp API allows users to interact with data from existing email campaigns under their account and to configure further campaigns.

This Parsons integration focuses on accessing information about previous email campaigns, including methods for fetching campaigns, members, emails, and unsubscribes.

Note

Authentication

Mailchimp requires an API key, which can be obtained from the ‘API Keys’ section of your Mailchimp account, assuming you have Manager privileges. For more information about Mailchimp authentication, see the Mailchimp help page about API Keys.

Quick Start

To instantiate the Mailchimp class, you can either store your Mailchimp API key as an environmental variable (MAILCHIMP_API_KEY) or pass it as an argument.

from parsons import Mailchimp

# First approach: API key is stored as an environmental variable
mc = Mailchimp()

# Second approach: Pass API key as argument
mc = Mailchimp(api_key='my_api_key')

# Get all recipient lists under a Mailchimp account
lists = mc.get_lists()

# Get campaigns sent since the beginning of 2020
recent_campaigns = mc.get_campaigns(since_send_time='2020-01-01T00:00:00Z')

# Get all unsubscribes from a campaign
unsubscribes = mc.get_unsubscribes('dd693a3e74')

API

class parsons.mailchimp.Mailchimp(api_key=None)

Instantiate Mailchimp Class

Args:

api_key:

The Mailchimp-provided application key. Not required if MAILCHIMP_API_KEY env variable set.

Returns:

Mailchimp Class

get_lists(fields=None, exclude_fields=None, count=None, offset=None, before_date_created=None, since_date_created=None, before_campaign_last_sent=None, since_campaign_last_sent=None, email=None, sort_field=None, sort_dir=None)

Get a table of lists under the account based on query parameters. Note that argument descriptions here are sourced from Mailchimp’s official API documentation.

Args:

fields: list of strings

A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.

exclude_fields: list of strings

A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

count: int

The number of records to return. Default value is 10. Maximum value is 1000.

offset: int

The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.

before_date_created: string

Restrict response to lists created before the set date. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

since_date_created: string

Restrict results to lists created after the set date. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

before_campaign_last_sent: string

Restrict results to lists created before the last campaign send date. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

since_campaign_last_sent: string

Restrict results to lists created after the last campaign send date. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

email: string

Restrict results to lists that include a specific subscriber’s email address.

sort_field: string, can only be ‘date_created’ or None

Returns files sorted by the specified field.

sort_dir: string, can only be ‘ASC’, ‘DESC’, or None

Determines the order direction for sorted results.

Returns:

Table Class

get_campaigns(fields=None, exclude_fields=None, count=None, offset=None, type=None, status=None, before_send_time=None, since_send_time=None, before_create_time=None, since_create_time=None, list_id=None, folder_id=None, member_id=None, sort_field=None, sort_dir=None)

Get a table of campaigns under the account based on query parameters. Note that argument descriptions here are sourced from Mailchimp’s official API documentation.

Args:

fields: list of strings

A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.

exclude_fields: list of strings

A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

count: int

The number of records to return. Default value is 10. Maximum value is 1000.

offset: int

The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.

type: string, can only be ‘regular’, ‘plaintext’, ‘absplit’, ‘rss’, ‘variate’, or None

The campaign type.

status: string, can only be ‘save’, ‘paused’, ‘schedule’, ‘sending’, ‘sent’, or None

The status of the campaign.

before_send_time: string

Restrict the response to campaigns sent before the set time. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

since_send_time: string

Restrict the response to campaigns sent after the set time. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

before_create_time: string

Restrict the response to campaigns created before the set time. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

since_create_time: string

Restrict the response to campaigns created after the set time. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

list_id: string

The unique id for the list.

folder_id: string

The unique folder id.

member_id: string

Retrieve campaigns sent to a particular list member. Member ID is The MD5 hash of the lowercase version of the list member’s email address.

sort_field: string, can only be ‘create_time’, ‘send_time’, or None

Returns files sorted by the specified field.

sort_dir: string, can only be ‘ASC’, ‘DESC’, or None

Determines the order direction for sorted results.

Returns:

Table Class

get_members(list_id, fields=None, exclude_fields=None, count=None, offset=None, email_type=None, status=None, since_timestamp_opt=None, before_timestamp_opt=None, since_last_changed=None, before_last_changed=None, unique_email_id=None, vip_only=False, interest_category_id=None, interest_ids=None, interest_match=None, sort_field=None, sort_dir=None, since_last_campaign=None, unsubscribed_since=None)

Get a table of members in a list based on query parameters. Note that argument descriptions here are sourced from Mailchimp’s official API documentation.

Args:

list_id: string

The unique ID of the list to fetch members from.

fields: list of strings

A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.

exclude_fields: list of fields as strings

A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

count: int

The number of records to return. Default value is 10. Maximum value is 1000.

offset: int

The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.

email_type: string

The email type.

status: string, can only be ‘subscribed’, ‘unsubscribed’, ‘cleaned’, ‘pending’, ‘transactional’, ‘archived’, or None

The subscriber’s status.

since_timestamp_opt: string

Restrict results to subscribers who opted-in after the set timeframe. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

before_timestamp_opt: string

Restrict results to subscribers who opted-in before the set timeframe. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

since_last_changed: string

Restrict results to subscribers whose information changed after the set timeframe. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

before_last_changed: string

Restrict results to subscribers whose information changed before the set timeframe. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

unique_email_id: string

A unique identifier for the email address across all Mailchimp lists. This parameter can be found in any links with Ecommerce Tracking enabled.

vip_only: boolean

A filter to return only the list’s VIP members. Passing true will restrict results to VIP list members, passing false will return all list members.

interest_category_id: string

The unique id for the interest category.

interest_ids: list of strings

Used to filter list members by interests. Must be accompanied by interest_category_id and interest_match. The value must be a comma separated list of interest ids present for any supplied interest categories.

interest_match: string, can only be ‘any’, ‘all’, ‘none’, or None

Used to filter list members by interests. Must be accompanied by interest_category_id and interest_ids. “any” will match a member with any of the interest supplied, “all” will only match members with every interest supplied, and “none” will match members without any of the interest supplied.

sort_field: string, can only be ‘timestamp_opt’, ‘timestamp_signup’, ‘last_changed’, or None

Returns files sorted by the specified field.

sort_dir: string, can only be ‘ASC’, ‘DESC’, or None

Determines the order direction for sorted results.

since_last_campaign: string

Filter subscribers by those subscribed/unsubscribed/pending/cleaned since last email campaign send. Member status is required to use this filter.

unsubscribed_since: string

Filter subscribers by those unsubscribed since a specific date. Using any status other than unsubscribed with this filter will result in an error.

Returns:

Table Class

get_campaign_emails(campaign_id, fields=None, exclude_fields=None, count=None, offset=None, since=None)

Get a table of individual emails from a campaign based on query parameters. Note that argument descriptions here are sourced from Mailchimp’s official API documentation.

Args:

campaign_id: string

The unique ID of the campaign to fetch emails from.

fields: list of strings

A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.

exclude_fields: list of strings

A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

count: int

The number of records to return. Default value is 10. Maximum value is 1000.

offset: int

The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.

since: string

Restrict results to email activity events that occur after a specific time. We recommend ISO 8601 time format: 2015-10-21T15:41:36+00:00.

Returns:

Table Class

get_unsubscribes(campaign_id, fields=None, exclude_fields=None, count=None, offset=None)

Get a table of unsubscribes associated with a campaign based on query parameters. Note that argument descriptions here are sourced from Mailchimp’s official API documentation.

Args:

campaign_id: string

The unique ID of the campaign to fetch unsubscribes from.

fields: list of strings

A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.

exclude_fields: list of strings

A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

count: int

The number of records to return. Default value is 10. Maximum value is 1000.

offset: int

The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.

Returns:

Table Class