Mail Event Audience

This article describes resources and services that enable you to read, create, and update email event audiences.

Overview

A mail event audience enables you to target consumers based on sales receipts.

Advertisers can define the parameters of their audience based on purchase confirmation emails in Yahoo users’ inboxes for individual products, airline bookings, hotel reservations and more.

A purchase receipt is defined as an individual, anonymized email that a Yahoo mail user receives indicating that the user completed a purchase or payment.

Endpoint

/traffic/audiences/mail_event

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to read an existing mail event audience.
  • Use the POST method to create a new mail event audience.
  • Use the PUT method to update an existing mail event audience.

Resources

Mail Event Object

The Mail Event object contains the following fields:

Field Description Type Create Update
id Specifies the audience ID. integer N/A Required
name Specifies the name of the audience. string Required Optional
status

Specifies the current status of the audience.

Allowed values:

  • ACTIVE: You can target the audience.
  • INACTIVE: You cannot target the audience.

Defaults to ACTIVE if you don’t specify a value.

 string Optional Optional
eventType

Specifies the mail event audience type. Options include:

  • FLIGHT - Consumers who have booked an airline reservation.
  • CAR - Consumers who have booked a car rental.
  • HOTEL - Consumers who have booked a hotel booking or confirmation.
  • MOVIE_TICKETS - Consumers who have purchased a movie ticket.
  • LIVE_EVENTS - Consumers who have purchased a ticket to a live event, like a concert.
  • INVOICES - Consumers who have received statements or bills.
  • PRODUCTS - Consumers who have purchased a particular product.
 string Required Optional
frequency

Specifies the minimum number of receipts that must be in the consumer’s email for that consumer to be included in the audience. Options include:

  • 1 (Default Value)
  • 2
  • 3
  • 4
  • 5
 integer Optional Optional
accountId Specifies the advertiser ID. If specified, the mail event audience is tied to a specific advertiser and can only be used in that advertiser’s campaigns. To learn more, see Advertisers. string Required Optional
createdAt A read-only field that specifies when the audience was created. string N/A N/A
textAttributes

Specifies an array of Text Attribute objects.

To learn more, see Text Attributes Object.

 array Optional Optional
timeAttributes

Specifies an array of Time Attribute objects.

To learn more, see Time Attribute Object.

 array Optional Optional

Text Attributes Object

The textAttributes array contains one or more Text Attribute objects. The Text Attribute object contains the following fields:

Field Description Type Create Update
key Specifies the attribute key. For a complete list, see Supported Purchase Events. string Required Required
groupType

Specifies the group type. Option include:

  • If INCLUDE is specified, the object specifies consumers to include in the audience.
  • If EXCLUDE is specified, the object specifies consumers to exclude from the audience.
 string Required Required
matchType

Specifies the match type. Options include:

  • If CONTAINS is specified, the object specifies consumers to include in the audience.
  • If EQUALS is specified, the object specifies consumers to exclude from the audience.

To learn more see, Supported Purchase Events.

[1](1, 2) Required if the value type of the attribute is String.
string Required [1] Required [1]
operatorType

Specifies the operator type. Options include:

  • If EQUAL_TO is specified, the object specifies consumers to include in the audience.
  • If GREATER_THAN is specified, the object specifies consumers to exclude from the audience.
  • If LESS_THAN is specified, the object specifies consumers to exclude from the audience.

To learn more see, Supported Purchase Events.

[2](1, 2) Required if the value type of the attribute is Numeric
string Required [2] Required [2]
values Specifies an array of keywords. array Required Required
name Read-only field showing the event name. string N/A N/A

Example Payload

{
  "textAttributes": [
    {
      "key": "cpv",
      "groupType": "INCLUDE",
      "values": [
        "aa.com",
        "advantage.com"
      ]
    }
  ]
}

Time Attribute Object

The timeAttributes array contains an array of Time Attribute objects. Time Attribute object are defined by the following fields:

Field Description Type Create Update
key

Specifies the attribute key.

For a complete list, see Supported Purchase Events.

 string Required Required
rangeType

Specifies the method used to select ranage of the data collection. Options include:

  • If DATE is specified, exact dates are used.
  • If DAY is specified, the range is comprised of past or future days.
 string Required Required
fromDate

Specifies the start of the date range.

[3](1, 2) Required if the rangeType is DATE. Format: yyyymmdd
string Required [3] Required [3]
toDate

Specifies the end of the date range.

[4](1, 2) Required if the rangeType is DATE. Format: yyyymmdd
string Required [4] Required [4]
numDays

Specifies the number of days into the past or future.

[5](1, 2) Required if the rangeType is DAY.
string Required [5] Required [5]
name Read-only field showing the event name. string N/A N/A

Example Payload

{
  "timeAttributes": [
    {
      "key": "cbkdt",
      "rangeType": "DATE",
      "fromDate": "20170703",
      "toDate": "20170903"
    },
    {
      "key": "cpickdt",
      "rangeType": "DAY",
      "numDays": "2"
    }
  ]
}

Supported Purchase Events

[This is the definition of a purchase event.]

  • string attributes can only be part of textAttributes
  • time attributes can only be included in timeAttributes.
Attribute Event Key Event Name Data Type Value Type
FLIGHT farcd airline string Search
FLIGHT fpv booking service string Search
FLIGHT fdeap travel from string Search
FLIGHT farap travel to string Search
FLIGHT fbkdt booking date time Timestamp
FLIGHT fdedt depart date time Timestamp
FLIGHT fardt arrival date time Timestamp
CAR cpv booked car with string Search
CAR ccity rental city string String
CAR ccountry rental country string Search
CAR cbkdt car booking date time Timestamp
CAR cpickdt pickup date time Timestamp
HOTEL hhname hotel name string String
HOTEL hpv booked hotel with string Search
HOTEL hbrand hotel brand string Search
HOTEL hcity hotel city string String
HOTEL hcountry hotel country string Search
HOTEL hdedt checkin date time` Timestamp
HOTEL hbkdt hotel booking date time Timestamp
HOTEL hnody length of stay string Numeric
LIVE_EVENTS lvevtname event name string String
LIVE_EVENTS lvevtvenue event venue string String
LIVE_EVENTS lvevtsender event email sender string Search
LIVE_EVENTS lvevtseason event season string Search
LIVE_EVENTS lvevtdate event date time Timestamp
MOVIE_TICKETS mvtixthtr movie theater name string String
MOVIE_TICKETS mvtixmvname movie title string String
MOVIE_TICKETS mvtixgenre movie genre string Search
MOVIE_TICKETS mvtixsender ticket vendor string Search
MOVIE_TICKETS mvtixrating movie rating string Search
MOVIE_TICKETS mvtixdate movie date time Timestamp
INVOICES iprovidername users making payment to string String
INVOICES ipaymentstatus payment status string Search
INVOICES ipaymentduedate payment due date time Timestamp
PRODUCTS itemname product name string String
PRODUCTS senderdomain bought from string Search
PRODUCTS topcategory category string Search
PRODUCTS subcategory subcategory string Search
PRODUCTS paymenttype payment method string Search
PRODUCTS orderdate purchase date time Timestamp
PRODUCTS itempriceusd product price string Numeric

Read Seat-Level Mail Event Audience

Get data for a specific seat-level mail event audience.

GET /traffic/audiences/mail_event/{id}

Parameters

Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Required

Example Request URL (Seat-Level)

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50335610

Example Response (Seat-Level)

{
  "response": {
    "id": 50335610,
    "name": "purtest130",
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "CAR",
    "textAttributes": [
      {
        "name": "booked car with",
        "key": "cpv",
        "groupType": "INCLUDE",
        "values": [
          "aa.com",
          "advantage.com"
        ]
      },
      {
        "name": "rental city",
        "key": "ccity",
        "groupType": "EXCLUDE",
        "matchType": "CONTAINS",
        "values": [
          "San Francisco",
          "San Jose",
          "Oakland"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "pickup date",
        "key": "cpickdt",
        "rangeType": "DAY",
        "numDays": "2"
      },
      {
        "name": "car booking date",
        "key": "cbkdt",
        "rangeType": "DATE",
        "fromDate": "20170703",
        "toDate": "20170903"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T05:11:03Z"
}

Read Advertiser-Level Mail Event Audience

Get data for a specific advertiser-level mail event audience.

GET /traffic/audiences/mail_event/{id}?accountId={accountId}

Parameters

Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Required
accountId query Specifies the advertiser ID. integer Required

Example Request URL (Advertiser-Level)

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50335609?accountId=1356341

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50335609,
    "name": "travel-test",
    "accountId": 1356341,
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "FLIGHT",
    "textAttributes": [
      {
        "name": "airline",
        "key": "farcd",
        "groupType": "INCLUDE",
        "values": [
          "UA"
        ]
      },
      {
        "name": "travel from",
        "key": "fdeap",
        "groupType": "EXCLUDE",
        "values": [
          "JFK"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "booking date",
        "key": "fbkdt",
        "rangeType": "DAY",
        "numDays": "2"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T05:08:19Z"
}

Read Attributes & Allowed Values

Get a list of attributes and allowed values.

GET /traffic/audiences/mail_event/allowedvalues/{eventType}

Each event type contains multiple attributes (such as hotel brand or hotel city). Certain attributes allow any value while others are restricted to specific set of values.

Parameters

Parameter Parameter Type Description Data Type Required
eventType path

Specifies the mail event type.

  • FLIGHT: Consumers who have booked an airline reservation.
  • CAR: Consumers who have booked a car rental.
  • HOTEL: Consumers who have booked a hotel booking or confirmation.
  • MOVIE_TICKETS: Consumers who have purchased a movie ticket.
  • LIVE_EVENTS: Consumers who have purchased a ticket to a live event, like a concert.
  • INVOICES: Consumers who have received statements or bills.
  • PRODUCTS: Consumers who have purchased a particular product.
 string Required

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/allowedvalues/HOTEL

Example Response (Partial)

The response contains the following fields:

{
  "response": {
    "categories": [
      {
        "attributeName": "hotel booking date",
        "allowedValues": []
      },
      {
        "attributeName": "checkin date",
        "allowedValues": []
      },
      {
        "attributeName": "hotel city",
        "allowedValues": []
      },
      {
        "attributeName": "hotel name",
        "allowedValues": []
      },
      {
        "attributeName": "length of stay",
        "allowedValues": []
      },
      {
        "attributeName": "booked hotel with",
        "allowedValues": [
          "0sg.net",
          "4huffs.com"
        ]
      },
      {
        "attributeName": "hotel brand",
        "allowedValues": [
          "BEST WESTERN HOTELS",
          "CHOICE HOTELS"
        ]
      },
      {
        "attributeName": "hotel country",
        "allowedValues": [
          "AND",
          "ARG"
        ]
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-08-30T04:01:45Z"
}

Create Mail Event Audience

Create a new mail event audience.

POST /traffic/audiences/mail_event

Audiences may be created at the seat-level or the advertiser-level. If no advertiser ID (accountId) is specified, the mail event audience is created at the seat level and is available to all advertisers belong to that seat.

Example Request URL (Seat-Level)

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event

Example Request Body (Seat-Level)

{
  "name": "purtest130",
  "textAttributes": [
    {
      "key": "cpv",
      "groupType": "INCLUDE",
      "values": [
        "aa.com",
        "advantage.com"
      ]
    },
    {
      "key": "ccity",
      "groupType": "EXCLUDE",
      "matchType": "CONTAINS",
      "values": [
        "San Francisco",
        "San Jose",
        "Oakland"
      ]
    }
  ],
  "timeAttributes": [
    {
      "key": "cbkdt",
      "rangeType": "DATE",
      "fromDate": "20170703",
      "toDate": "20170903"
    },
    {
      "key": "cpickdt",
      "rangeType": "DAY",
      "numDays": "2"
    }
  ],
  "eventType": "CAR",
  "accountId": null,
  "status": "ACTIVE",
  "frequency": 1
}

Example Response (Seat-Level)

{
  "response": {
    "id": 50335610,
    "name": "purtest130",
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "CAR",
    "textAttributes": [
      {
        "name": "booked car with",
        "key": "cpv",
        "groupType": "INCLUDE",
        "values": [
          "aa.com",
          "advantage.com"
        ]
      },
      {
        "name": "rental city",
        "key": "ccity",
        "groupType": "EXCLUDE",
        "matchType": "CONTAINS",
        "values": [
          "San Francisco",
          "San Jose",
          "Oakland"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "pickup date",
        "key": "cpickdt",
        "rangeType": "DAY",
        "numDays": "2"
      },
      {
        "name": "car booking date",
        "key": "cbkdt",
        "rangeType": "DATE",
        "fromDate": "20170703",
        "toDate": "20170903"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T05:11:03Z"
}

Example Request Body (Advertiser-Level)

{
  "name": "travel-test",
  "textAttributes": [
    {
      "key": "airline",
      "groupType": "INCLUDE",
      "values": [
        "UA"
      ]
    },
    {
      "key": "travel from",
      "groupType": "EXCLUDE",
      "values": [
        "JFK"
      ]
    }
  ],
  "timeAttributes": [
    {
      "key": "booking date",
      "rangeType": "DAY",
      "numDays": "2"
    }
  ],
  "eventType": "FLIGHT",
  "accountId": 1356341,
  "status": "ACTIVE",
  "frequency": 1
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50335609,
    "name": "travel-test",
    "accountId": 1356341,
    "frequency": 1,
    "createdAt": "2017-09-23",
    "status": "ACTIVE",
    "eventType": "FLIGHT",
    "textAttributes": [
      {
        "name": "airline",
        "key": "farcd",
        "groupType": "INCLUDE",
        "values": [
          "UA"
        ]
      },
      {
        "name": "travel from",
        "key": "fdeap",
        "groupType": "EXCLUDE",
        "values": [
          "JFK"
        ]
      }
    ],
    "timeAttributes": [
      {
        "name": "booking date",
        "key": "fbkdt",
        "rangeType": "DAY",
        "numDays": "2"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-23T04:56:01Z"
}

Update Mail Event Audience

Update an existing mail event audience.

PUT /traffic/audiences/mail_event/{id}

Partial updates are supported for all fields except timeAttributes; values of supported fields which are not in the payload will remain unchanged.

Example Request URL (Seat-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50336118

Example Request Body (Seat-Level)

{
  "name": "new_name_purchase_event",
  "textAttributes": [
    {
      "key": "cpv",
      "groupType": "INCLUDE",
      "values": [
        "aa.com",
        "advantage.com"
      ]
    }
  ]
}

Example Response (Seat-Level)

{
  "response": {
    "id": 50336118,
    "name": "new_name_purchase_event",
    "frequency": 1,
    "createdAt": "2017-09-25",
    "status": "INACTIVE",
    "eventType": "CAR",
    "textAttributes": [
      {
        "name": "booked car with",
        "key": "cpv",
        "groupType": "INCLUDE",
        "values": [
          "aa.com",
          "advantage.com"
        ]
      }
    ],
    "timeAttributes": []
  },
  "errors": null,
  "timeStamp": "2017-09-25T18:11:47Z"
}

Example Request Body (Advertiser-Level)

{
  "name": "new_name_purchase_event_adv",
  "accountId": 1356341,
  "textAttributes": [
    {
      "key": "ccity",
      "groupType": "EXCLUDE",
      "matchType": "CONTAINS",
      "values": [
        "San Francisco",
        "San Jose",
        "Oakland"
      ]
    }
  ]
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50336118,
    "name": "new_name_purchase_event_adv",
    "accountId": 1356341,
    "frequency": 1,
    "createdAt": "2017-09-25",
    "status": "INACTIVE",
    "eventType": "CAR",
    "textAttributes": [
      {
        "name": "rental city",
        "key": "ccity",
        "groupType": "EXCLUDE",
        "matchType": "CONTAINS",
        "values": [
          "San Francisco",
          "San Jose",
          "Oakland"
        ]
      }
    ],
    "timeAttributes": []
  },
  "errors": null,
  "timeStamp": "2017-09-25T18:14:17Z"
}

Delete Mail Event Audience

The DSP Traffic API does not support deletion of mail event audiences.