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

You can read, update, and create mail event audiences via the mail event resource.

/traffic/audiences/mail_event
  • Use the GET method to read mail event audience data.
  • Use the POST method to create new mail event audiences.
  • Use the PUT method to update existing mail event audiences.

Resources

Mail Event Object

The Mail Event object contains the following fields:

Table 54 Email Address Audience Resource
Field Description Type Add Update
id Specifies the audience ID. integer N/A Required
name Specifies the name of the audience. string Required Optional
pixelId Specifies the name of the pixel ID. string Required 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
  • 2
  • 3
  • 4
  • 5
integer Required 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 Read-only field that records the date 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:

Table 55 Text Attribute Object Fields
Field Description Type Add 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

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:

Table 56 Time Attribute Object Fields
Field Description Type Add 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.
integer Required [3] Required [3]
fromDate

Specifies the end of the date range.

[4](1, 2) Required if the rangeType is DATE.
integer Required [4] Required [4]
numDays

Specifies the number of days into the past or future.

[5](1, 2) Required if the rangeType is DAY.
integer Required [5] Required [5]

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.
Table 57 Purchase Events Supported
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 Audience

Returns data for the specified seat-level mail event audience.

GET /traffic/audiences/mail_event/{id}

Parameters

Table 58 Read Advertiser-Level Mail Event Audience Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Required

Example Request

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

Example Response

{
  "response": {
    "id": 50335610,
    "name": "purtest130",
    "frequency": 1,
    "pixelId": 10026620,
    "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 Audience

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

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

Parameters

Table 59 Read Advertiser-Level Mail Event Audience Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Required
accountId query Specifies the advertiser’s account ID. integer Required

Example Request

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

Example Response

{
  "response": {
    "id": 50335609,
    "name": "travel-test",
    "accountId": 1356341,
    "frequency": 1,
    "pixelId": 10026620,
    "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

Returns 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

Table 60 Read Advertiser-Level Mail Event Audience 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

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

Example Response (Partial)

The response contains the following fields:

{
  "response": {
    "pixelId": 10026620,
    "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"
i

Update Audience

Updates an existing mail event audience.

PUT /traffic/audiences/mail_event/{id}

Partial update is supported for all fields except timeAttributes; fields that are either not passed or passed as null will be ignored during update.

Parameters

Table 61 Update Mail Event Audience Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Required
name body Specifies the name of the audience. string Optional
pixelId body Specifies the name of the pixel ID. string Optional
eventType body

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 Optional
frequency body

Specifies the number of receipts. Options include:

  • 1
  • 2
  • 3
  • 4
  • 5
integer Optional
accountId body

Specifies the advertiser ID.

[6]If you update an advertiser-level audience, the accountId is required.

Note: To create a seat-level audience, set this field to null.

string Optional [6]
textAttributes body

Specifies an array of Text Attribute objects.

To learn more, see Text Attributes Object.

array Optional
timeAttributes body

Specifies an array of Time Attribute objects.

To learn more, see Time Attribute Object.

Note: Existing values will be removed if null or empty array is specified.

array Optional

Example Request

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

Example Payload (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,
    "pixelId": 10026620,
    "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 Payload (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,
    "pixelId": 10026620,
    "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"
}

Create Audiences

Creates 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.

Parameters

All parameters are specified in the body of the application/json payload.

Table 62 Create Mail Event Audience Parameters
Parameter Parameter Type Description Data Type Required
id body Specifies the audience ID. integer Required
name body Specifies the name of the audience. string Optional
pixelId body Specifies the name of the pixel ID. string Optional
eventType body

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 Optional
frequency body

Specifies the number of receipts. Options include:

  • 1
  • 2
  • 3
  • 4
  • 5
integer Optional
accountId body

Specifies the advertiser ID.

[7]If you update an advertiser-level audience, the accountId is required.

Note: To create a seat-level audience, set this field to null.

string Optional [7]
textAttributes body

Specifies an array of Text Attribute objects.

To learn more, see Text Attributes Object.

array Optional
timeAttributes body

Specifies an array of Time Attribute objects.

To learn more, see Time Attribute Object.

Note: Existing values will be removed if null or empty array is specified.

array Optional

Example Request (Seat-Level)

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

For a seat-level audience, you must specify the audience ID:

{
  "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,
  "pixelId": 10026620,
  "status": "ACTIVE",
  "frequency": 1
}

Example Response (Seat-Level)

{
  "response": {
    "id": 50335610,
    "name": "purtest130",
    "frequency": 1,
    "pixelId": 10026620,
    "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 Payload (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,
  "pixelId": 10026620,
  "status": "ACTIVE",
  "frequency": 1
}

Example Response (Advertiser-Level)

{
  "response": {
    "id": 50335609,
    "name": "travel-test",
    "accountId": 1356341,
    "frequency": 1,
    "pixelId": 10026620,
    "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"
}

Delete Audience

Audience deletion is not supported by the API.