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 file, you need to encrypt it. That means, you must lowercase the file names and remove 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"
      }
  ]
}