Mailchimp
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 and the recipients of those campaigns.
Quick Start
from parsons import Mailchimp
mc = Mailchimp()
# 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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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