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

View Mail Event Audience

View a specific mail event audience.

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

Parameters

Parameters

Parameter Type

Description

Data Type

Required/Optional

id

path

Specifies the audience ID.

integer

Required

accountId

query

Specifies the advertiser ID.

integer

Required for advertiser-level audiences. Do not use for seat-level audiences.

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

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

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 belonging 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 URL (Advertiser-Level)

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/mail_event/50336118?accountId=1356341

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.