Mail Event Audience¶
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:
Defaults to |
string |
Optional | Optional |
pixelId |
Specifies the name of the pixel ID. | string |
Required | Optional |
eventType |
Specifies the mail event audience type. Options include:
|
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:
|
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 |
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:
|
string |
Required | Required | ||
matchType |
Specifies the match type. Options include:
To learn more see, Supported Purchase Events.
|
string |
Required [1] | Required [1] | ||
operatorType |
Specifies the operator type. Options include:
To learn more see, Supported Purchase Events.
|
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:
|
string |
Required | Required | ||
fromDate |
Specifies the start of the date range.
|
string |
Required [3] | Required [3] | ||
toDate |
Specifies the end of the date range.
|
string |
Required [4] | Required [4] | ||
numDays |
Specifies the number of days into the past or future.
|
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 oftextAttributes
time
attributes can only be included intimeAttributes
.
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,
"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 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,
"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¶
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.
|
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": {
"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"
}
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.
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 pixel ID. | integer |
Optional | ||
eventType |
body | Specifies the mail event audience type. Options include:
|
string |
Optional | ||
frequency |
body | Specifies the number of receipts. Options include:
|
integer |
Optional | ||
accountId |
body | Specifies the advertiser ID.
Note: To create a seat-level audience, set this field to |
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 |
array |
Optional |
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,
"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 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,
"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 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.
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 pixel ID. | integer |
Optional | ||
eventType |
body | Specifies the mail event audience type. Options include:
|
string |
Optional | ||
frequency |
body | Specifies the number of receipts. Options include:
|
integer |
Optional | ||
accountId |
body | Specifies the advertiser ID.
Note: To create a seat-level audience, set this field to |
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 |
array |
Optional |
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,
"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 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,
"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 Mail Event Audience¶
The DSP Traffic API does not support deletion of mail event audiences.