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

    An individual segment condition

    Show Properties
  • Automation
    object

    An individual segment condition

    Show Properties
  • CampaignPoll
    object

    An individual segment condition

    Show Properties
  • Conversation
    object

    An individual segment condition

    Show Properties
  • Date
    object

    An individual segment condition

    Show Properties
  • EmailClient
    object

    An individual segment condition

    Show Properties
  • Language
    object

    An individual segment condition

    Show Properties
  • MemberRating
    object

    An individual segment condition

    Show Properties
  • SignupSource
    object

    An individual segment condition

    Show Properties
  • SurveyMonkey
    object

    An individual segment condition

    Show Properties
  • VIP
    object

    An individual segment condition

    Show Properties
  • Interests
    object

    An individual segment condition

    Show Properties
  • EcommCategory
    object

    An individual segment condition

    Show Properties
  • EcommNumber
    object

    An individual segment condition

    Show Properties
  • EcommPurchased
    object

    An individual segment condition

    Show Properties
  • EcommSpent
    object

    An individual segment condition

    Show Properties
  • EcommStore
    object

    An individual segment condition

    Show Properties
  • GoalActivity
    object

    An individual segment condition

    Show Properties
  • GoalTimestamp
    object

    An individual segment condition

    Show Properties
  • FuzzySegment
    object

    An individual segment condition

    Show Properties
  • StaticSegment
    object

    An individual segment condition

    Show Properties
  • IPGeoCountryState
    object

    An individual segment condition

    Show Properties
  • IPGeoIn
    object

    An individual segment condition

    Show Properties
  • IPGeoInZip
    object

    An individual segment condition

    Show Properties
  • IPGeoUnknown
    object

    An individual segment condition

    Show Properties
  • IPGeoZip
    object

    An individual segment condition

    Show Properties
  • SocialAge
    object

    An individual segment condition

    Show Properties
  • SocialGender
    object

    An individual segment condition

    Show Properties
  • SocialInfluence
    object

    An individual segment condition

    Show Properties
  • SocialNetworkMember
    object

    An individual segment condition

    Show Properties
  • SocialNetworkFollow
    object

    An individual segment condition

    Show Properties
  • AddressMerge
    object

    An individual segment condition

    Show Properties
  • ZipMerge
    object

    An individual segment condition

    Show Properties
  • BirthdayMerge
    object

    An individual segment condition

    Show Properties
  • DateMerge
    object

    An individual segment condition

    Show Properties
  • SelectMerge
    object

    An individual segment condition

    Show Properties
  • TextMerge
    object

    An individual segment condition

    Show Properties
  • EmailAddress
    object

    An individual segment condition

    Show Properties
  • PredictedGender
    object

    An individual segment condition

    Show Properties
  • PredictedAge
    object

    An individual segment condition

    Show Properties
  • NewSubscribers
    object

    An individual segment condition

    Show Properties