Mailchimp Developer LogoMailchimp Developer Wordmark

Alternative Schemas

The basics

The Mailchimp Marketing API has several endpoints that are capable of accepting or returning multiple types of data. The API specifies alternative schemas for these endpoints, with additional parameters for requesting a particular type of data.

This documentation covers the Marketing API’s implementation of alternative schemas, including tables of the supported alternative schemas and their parameters. For further details on other aspects of these endpoints, consult the full API reference.

Structure

To specify alternate schemas, the Marketing API uses x-oneOf, a variation on the Open API Specification’s oneOf keyword. The value of x-oneOf is an array of objects, each representing a possible schema for the endpoint.

To choose among alternative schemas, you need to know the name of the schema and the field where you provide that name. The name of each schema is the x-value inside the schema object. The field name for a particular endpoint is specified as the propertyName of its x-discriminator object. Your code should be able to handle any type of data based on its x-value, or you should limit your API calls to the data types you want to handle.

For example, say you want to add a segment using a conditions parameter to determine who is included in the segment. This parameter’s specification indicates that it uses alternative schemas with the x-discriminator named condition_type. Find the x-value of the type of segment you want to create and pass that within conditions.

For some endpoints, specifying a particular schema affects not only the type of data returned, but also the other values you can pass in your request. Operators for comparing data are given in the op field, and valid comparisons are given in the value field.

Activity schemas

The Member Activity Feed endpoint can return a range of activity types. Although the x-discriminator for these activity schemas is activity_type, the relevant request parameter is activity_filters, which accepts an array of x-values instead of a single string. If you pass activity_filters, activity matching one of the provided types will be returned; if you omit it, any type of activity that matches your query will be returned.

  • open
    object

    Activity feed item representing opening an email.

    Show Properties
  • click
    object

    Activity feed item representing having a link clicked by a contact.

    Show Properties
  • bounce
    object

    Activity feed item representing an email to this contact bouncing.

    Show Properties
  • unsub
    object

    Activity feed item representing this contact unsubscribing from a list.

    Show Properties
  • sent
    object

    Activity feed item representing having an email sent to the contact.

    Show Properties
  • conversation
    object

    Activity feed item representing an individual reply in a conversation.

    Show Properties
  • note
    object

    Activity feed item representing a note on the contact record.

    Show Properties
  • marketing_permission
    object

    Activity feed item indicating if a marketing permission was added or updated.

    Show Properties
  • postcard_sent
    object

    Activity feed item representing a time when a contact was sent a particular postcard.

    Show Properties
  • squatter_signup
    object

    Activity feed item to representing a contact signing up for the audience from a squatter page.

    Show Properties
  • website_signup
    object

    Activity feed item to representing a contact signing up for the contact through a website page.

    Show Properties
  • landing_page_signup
    object

    Activity feed item to representing a contact signing up for the list via a landing page.

    Show Properties
  • ecommerce_signup
    object

    Activity feed item to representing a contact signing up for the list via a ecommerce store.

    Show Properties
  • generic_signup
    object

    Activity feed item that represents a contact signing up for the audience via a generic some generic method (specifically, one we can't link to).

    Show Properties
  • order
    object

    Activity feed item that represents an order.

    Show Properties
  • event
    object

    Activity feed item that represents a generic event.

    Show Properties
  • survey_response
    object

    Represents when a contact completes and submits a survey

    Show Properties
  • Segment condition schemas

    A variety of endpoints accept or return segment condition data, from the Segments endpoints themselves to others like automation, list, and campaign endpoints. Because there are many ways to define a segment, there are many alternative schemas for segment conditions. 

    The x-discriminator for segment conditions is condition_type. The request parameter conditions accepts an array of objects that indicate the desired segment condition (field), operator, value, and optional extra information. Multiple segment conditions can be combined like so:

    Multiple segment conditions

    JSON
    {
       "name": "Gmail users who subscribed in 2021 or later",
       "options": {
           "match": "all",
           "conditions": [
               {
                   "field": "timestamp_opt",
                   "op":  "greater",
                   "value": "date",
                   "extra": "2021-01-01"
               },
               {
                   "field": "EMAIL",
                   "op":  "contains",
                   "value": "gmail.com"
               }
           ]
       }
    }
    
  • Aim
    object

    Segment by interaction with a specific campaign.

    Show Properties
  • Automation
    object

    Segment by interaction with an Automation workflow.

    Show Properties
  • CampaignPoll
    object

    Segment by poll activity.

    Show Properties
  • Conversation
    object

    Segment by interaction with a campaign via Conversations.

    Show Properties
  • Date
    object

    Segment by a specific date field.

    Show Properties
  • EmailClient
    object

    Segment by use of a particular email client.

    Show Properties
  • Language
    object

    Segment by language.

    Show Properties
  • MemberRating
    object

    Segment by member rating.

    Show Properties
  • SignupSource
    object

    Segment by signup source.

    Show Properties
  • SurveyMonkey
    object

    Segment by interaction with a SurveyMonkey survey.

    Show Properties
  • VIP
    object

    Segment by VIP status.

    Show Properties
  • Interests
    object

    Segment by an interest group merge field.

    Show Properties
  • EcommCategory
    object

    Segment by purchases in specific items or categories.

    Show Properties
  • EcommNumber
    object

    Segment by average spent total, number of orders, total number of products purchased, or average number of products per order.

    Show Properties
  • EcommPurchased
    object

    Segment by whether someone has purchased anything.

    Show Properties
  • EcommSpent
    object

    Segment by amount spent on a single order or across all orders.

    Show Properties
  • EcommStore
    object

    Segment by purchases from a specific store.

    Show Properties
  • GoalActivity
    object

    Segment by Goal activity.

    Show Properties
  • GoalTimestamp
    object

    Segment by most recent interaction with a website.

    Show Properties
  • FuzzySegment
    object

    Segment by similar subscribers.

    Show Properties
  • StaticSegment
    object

    Segment by a given static segment.

    Show Properties
  • IPGeoCountryState
    object

    Segment by a specific country or US state.

    Show Properties
  • IPGeoIn
    object

    Segment by a specific geographic region.

    Show Properties
  • IPGeoInZip
    object

    Segment by a specific US ZIP code.

    Show Properties
  • IPGeoUnknown
    object

    Segment members whose location information is unknown.

    Show Properties
  • IPGeoZip
    object

    Segment by a specific US ZIP code.

    Show Properties
  • SocialAge
    object

    Segment by age ranges in Social Profiles data.

    Show Properties
  • SocialGender
    object

    Segment by listed gender in Social Profiles data.

    Show Properties
  • SocialInfluence
    object

    Segment by influence rating in Social Profiles data.

    Show Properties
  • SocialNetworkMember
    object

    Segment by social network in Social Profiles data.

    Show Properties
  • SocialNetworkFollow
    object

    Segment by social network in Social Profiles data.

    Show Properties
  • AddressMerge
    object

    Segment by an address-type merge field.

    Show Properties
  • ZipMerge
    object

    Segment by an address-type merge field within a given distance.

    Show Properties
  • BirthdayMerge
    object

    Segment by a contact's birthday.

    Show Properties
  • DateMerge
    object

    Segment by a given date merge field.

    Show Properties
  • SelectMerge
    object

    Segment by a given dropdown or radio button merge field.

    Show Properties
  • TextMerge
    object

    Segment by a given text or number merge field.

    Show Properties
  • EmailAddress
    object

    Segment by email address.

    Show Properties
  • PredictedGender
    object

    Segment by predicted gender.

    Show Properties
  • PredictedAge
    object

    Segment by predicted age.

    Show Properties
  • NewSubscribers
    object

    Segment by when people subscribed.

    Show Properties