Mail Event (Purchase Receipt) Audience

Overview

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

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

Fields

The Mail Event object contains the following fields:

Name Description Type Add Update
id ID of the audience segment. integer N/A Required
name Name of the segment. text Required Optional
pixelId Pixel Id integer Required Optional
eventType

Mail event audience type.

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

Number of receipts.

  • 1
  • 2
  • 3
  • 4
  • 5 - Five or more
integer Required Optional
status

Current status of the segment.

  • ACTIVE - (Default Value) Active.
  • INACTIVE - Inactive
text Optional Optional
isGlobal

Indicate whether the segment is at Seat or Advertiser level.

  • true - Seat-level audience can be used for all the advertisers across your seat. Ensure that accountId is null to create a seat-level audience.
  • false - Advertiser-level audience is available for a single adversier. You must provide an accountId for this option.
text Required Required
accountId Advertiser/account ID to associate this segment with when creating or updating an advertiser-level audience. (1) Required when isGlobal is false. (2) Required when updating an existing advertiser-level audience. Refer to Advertisers. integer Required (1) Required (2)
createdAt (Read-Only) Creation timestamp. datetime N/A N/A
textAttributes Included or excluded text attributes. Refer to Text Attributes. array Optional Optional
timeAttributes Included time attributes. Refer to Time Attributes. Note Existing values will be removed if null or empty array is supplied during an Update. array Optional Optional

textAttributes object

Each element in the textAttributes object contains the following fields:

Name Description Type Add Update
key Attribute key. Refer to Supported Events for a full list. text Required Required
groupType
  • INCLUDE - Users you want the audience to include.
  • EXCLUDE - Users you want the audience to exclude.
text Required Required
matchType

Refer to Supported Events <#supported-purchase-events>. (1) Required for attributes whose Value Type is String.

  • CONTAINS - Match keywords with words or phrases containing the characters in the keywords.
  • EQUALS - The entire string must match in order to qualify.
text Required (1) Required (1)
operatorType

Refer to Supported Events <#supported-purchase-events>. (1) Required for attributes whose Value Type is Numeric.

  • EQUAL_TO
  • GREATER_THAN
  • LESS_THAN
text Required (1) Required (1)
values Array containing keywords to match. array Required Required

Example Payload

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

timeAttributes object

Each element in the timeAttributes object contains the following fields:

Name Description Type Add Update
key Attribute key. Refer to Supported Events for a full list. text Required Required
rangeType
  • DATE - Measure the time frame using the exact dates.
  • DAY - Measure the time frame in a number of (past or future) days.
text Required Required
numDays Number of days in the past or into the future you want the audience data collection to occur. A negative value indicates days in the past. (1) Required when rangeType is DAY. integer Required (1) Required (1)

Example Payload

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

Supported Purchase Events

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

Note Events designted with attribute type text can only be part of textAttributes, time attributes can only be included in timeAttributes.

Read Seat-Level Audience (Single)

To retrieve data for a specific Seat-Level Mail Event Audience, make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/{id}
Name Description Type Required?
id Audience / Segment ID integer Y

The response will be the Audience segment associated with the given ID.

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",
    "isGlobal": true,
    "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 (Single)

To retrieve data for a specific Advertiser-Level Mail Event Audience, make a GET call with the parameters specified below.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/{id}?accountId={accountId}
Name Description Type Required?
id Audience / Segment ID integer Y
accountId Account or Advertiser ID integer Y

The response will be the Audience segment associated with the given ID.

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",
    "isGlobal": false,
    "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"
}

Update Audience

To update an existing Mail Event Audience, make a PUT call with a payload body and id parameter. The response will be the updated Audience.

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

Note When updating an Advertiser-Level audience, isGlobal and accountId fields are required.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/{id}
Name Description Type Required?
id Audience / Segment ID integer Y

Example Request

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

Example Payload (Seat-Level)

{
  "name": "new_name_purchase_event",
  "isGlobal": true,
  "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",
    "isGlobal": true,
    "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",
  "isGlobal": false,
  "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",
    "isGlobal": false,
    "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 Audience

To create a new Mail Event Audience, make a POST call with a payload body. The response will be the newly created Audience.

Example Request

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

Example Payload (Seat-Level)

{
  "name": "purtest130",
  "isGlobal": true,
  "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",
    "isGlobal": true,
    "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",
  "isGlobal": true,
  "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",
    "isGlobal": false,
    "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.

Read Attributes & Allowed Values

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. To obtain a list of these attributes and the allowed values for each, use the endpoint documented below.

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/allowedvalues/{eventType}
Name Description Type Required?
eventType

Mail event audience type.

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

The response contains the following fields:

Name Description
pixelId Pixel ID. Required when creating the audience.
categories

Array containing allowed values for each attribute name. Each item contains the following fields:

  • attributeName - Attribute name. Required when creating the audience.
  • allowedValues - If an attribute allows only specific values, these will be listed here.

Example Request

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

Example Response (Partial)

{
  "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"
}