Audiences from your email lists

Overview

Audiences from your email lists allow you to define and target audience segments of people who are on your mailing lists. Once created, these segments will be available for targeting, using the TargetingAttribute service.

Fields

Custom audiences from email lists have the following fields:

Name Description Type Add Update
id The unique identifier of the audience. long N/A Required
advertiserid The id of the advertiser that owns the audience. long Required Read-Only
name The name of the audience segment. Maximum is 255 characters. string Required Optional
description A description for the segment. Maximum is 255 characters. string Optional Optional
type The custom audience type. Must be set to EMAIL. enum Required Required
cnt24h Unique user count for the last 24 hours. long Read-Only Read-Only
cnt30d Unique user count for the last 30 days. long Read-Only Read-Only
status The status of the segment. Can be ACTIVE or DELETED, and is set to ACTIVE by default. enum Optional Optional

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/audience

Create a new custom audience from an email list

Method: To create a new custom audience from an email list, make a POST call to the audience endpoint with the required fields. The response will be the newly created audience.

For example:

POST https://api.gemini.yahoo.com/v3/rest/audience

Data passed

 {
   "name": "test123123123",
   "type": "EMAIL",
   "advertiserId": 1119969,
   "description": ""
}

Example response

{
  "errors": null,
  "timestamp": "2015-11-11 17:35:32",
  "response": {
      "type": "EMAIL",
      "id": 20562365,
      "advertiserId": 1119969,
      "name": "test123123123",
      "description": "",
      "status": "ACTIVE"
  }
}

Upload a new custom audience from an email list

Important

To upload a new custom audience from an email list, you must pass the hashmode query parameter:

https://api.gemini.yahoo.com/v3/rest/audience/20562365/emails?hashmode=SHA256
form-data: file=[UPLOADED FILE]

Example response

{
  "errors": null,
  "timestamp": "2015-11-11 17:36:04",
  "response": {
      "status": "PROCESSING"
  }
}

Important

Before uploading your CSV file, you need to encrypt it with SHA256. That means, you must convert your email list to a hash which you would then place in your CSV file. For example: If the original email is barry@oath.com, the hashed value in the file would be d48adb3c108a657adf7597921f3bfc591ee3f00d658d2d288e0bb396ac0d5964. Your file name must also be lowercase and contain no spaces. The Gemini API only supports pre-encrypted files. Once the files are encrypted, all the personal data that resides on the files will be protected, using the SHA256 function, so that no raw emails are ever stored.

Important

There is a limit of 100,000 emails per upload.

Check upload progress

Your segment will be updated within minutes with the list of people on your email lists. You can check the status of the most recent upload by making a GET call to

https://api.gemini.yahoo.com/v3/rest/audience/20562365/emails

Example response

{
  "errors": null,
  "timestamp": "2015-11-11 17:34:30",
  "response": [
      {
          "statusId": "17066",
          "name": "Distribution20562365",
          "status": "ACTIVE"
      }
  ]
}