Adestra

Adestra enables publishers to deliver personalized email campaigns and newsletters using audience segmentation and analytics.

Setup

Troubleshooting

Overview

Adestra is an email service provider (ESP) that enables publishers to deliver personalized email campaigns, newsletters, and automated marketing communications. The Adestra integration is a Destination integration that allows you to activate Permutive cohorts directly into Adestra for use in email marketing campaigns. This integration is a Destination:

Destination: Permutive sends cohort memberships to Adestra, where they are represented as Contact lists. These lists can be used to trigger automated email campaigns or target users in marketing workflows.

Use cases include:

Send Permutive cohorts to Adestra to trigger automated email campaigns when users enter a cohort
Use behavioral and demographic cohorts for personalized email experiences
Leverage Permutive’s first-party data for email targeting and segmentation
Create timely, relevant email campaigns based on real-time user actions and cohort membership

Environment Compatibility

Environment	Supported	Notes
Web		Requires Contact ID to be passed via identity management
iOS		Requires Contact ID to be passed via identity management
Android		Requires Contact ID to be passed via identity management
CTV		Requires Contact ID to be passed via identity management
API Direct		Requires Contact ID to be passed via identity management

Prerequisites

Adestra Account - You must have an active Adestra account with API access enabled.
Adestra API Key - You will need your Adestra API key to configure the integration in the Permutive dashboard. This key should have permissions to manage contacts and lists.
Adestra Contact Lists - You must create Contact lists in Adestra ahead of time. The integration will add and remove users from these pre-existing lists based on cohort membership, but it will not automatically create new lists.
Contact ID Configuration - You must configure Permutive to collect Adestra Contact IDs (Adestra’s internal user identifier) and pass them to Permutive via identity management. The identity type must match the “Alias tag” configured in the Permutive dashboard.
Identity Management Setup - You need to implement identity management to associate Permutive users with Adestra Contact IDs. This is typically done using the Permutive Identify API or SDK identify methods.

Setup

Create Contact Lists in Adestra

Before enabling the integration in Permutive, create the Contact lists in Adestra that you want to sync cohorts to. Make note of each list’s List ID, as you’ll need these when activating cohorts.You can find List IDs in the Adestra UI by navigating to your lists and viewing the list details.

Enable Integration in Permutive Dashboard

In the Permutive dashboard, navigate to your workspace’s integrations page. Click Add Integration and select Adestra.You will be asked to provide:

Adestra API Key - Your Adestra API authentication key
Alias tag - The identity type name you’ll use to sync Contact IDs with Permutive (defaults to adestra)

The “Alias tag” field specifies the name of the identity type that Permutive will use to match users with their Adestra Contact IDs. This must correspond to the identity type you use when calling Permutive’s identity management APIs.

Configure Identity Management

Implement identity management to pass Adestra Contact IDs to Permutive. You can use the Permutive SDK or the Identify API.Example using Web SDK:

permutive.identify([
  {
    id: "12345", // Adestra Contact ID
    tag: "adestra", // Must match the Alias tag from Step 2
    priority: 0
  }
]);

Example using Identify API:

curl -XPOST https://api.permutive.com/v2.0/identify \
  -H 'X-API-Key: <PUBLIC_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "<PERMUTIVE_ID>",
    "aliases": [
      {
        "id": "<ADESTRA_CONTACT_ID>",
        "tag": "adestra",
        "priority": 0
      }
    ]
  }'

The Contact ID is Adestra’s internal identifier for a user. You’ll need to retrieve this from Adestra and pass it to Permutive whenever you identify a user.

Activate Cohorts to Adestra

In the Permutive Dashboard, navigate to one of your cohorts. You should see the Adestra activation option available.When enabling a cohort activation, you’ll need to provide:

Adestra List ID - The ID of the Adestra Contact list you want to sync this cohort to

Toggle the activation to On. Once enabled, Permutive will begin sending cohort membership updates to Adestra in near real-time (typically within 10 seconds of a user entering or exiting a cohort).

Verify Setup

After activating a cohort, verify that users are being added to the corresponding Contact list in Adestra:

Check the Contact list in the Adestra UI to see if users are appearing
Monitor the Permutive Events page to ensure identity events are being collected with the correct Adestra Contact IDs
Verify that cohort membership changes are reflected in Adestra within the expected timeframe

For web properties, implement identity management using the Permutive Web SDK:

// Identify users with their Adestra Contact ID
permutive.identify([
  {
    id: "12345", // Adestra Contact ID
    tag: "adestra", // Must match the Alias tag configured in dashboard
    priority: 0
  }
]);

You should call permutive.identify() whenever you have the user’s Adestra Contact ID available (typically after login or when the Contact ID is retrieved from your authentication system).

For iOS applications, implement identity management using the Permutive iOS SDK:

// Identify users with their Adestra Contact ID
Permutive.shared.identify(
  identifiers: [
    Identifier(
      id: "12345", // Adestra Contact ID
      tag: "adestra", // Must match the Alias tag configured in dashboard
      priority: 0
    )
  ]
)

You should call Permutive.shared.identify() whenever you have the user’s Adestra Contact ID available.

For Android applications, implement identity management using the Permutive Android SDK:

// Identify users with their Adestra Contact ID
Permutive.getInstance().identify(
  listOf(
    Identifier(
      id = "12345", // Adestra Contact ID
      tag = "adestra", // Must match the Alias tag configured in dashboard
      priority = 0
    )
  )
)

You should call Permutive.getInstance().identify() whenever you have the user’s Adestra Contact ID available.

For server-side implementations or environments without an SDK, use Permutive’s Identify API directly to pass Adestra Contact IDs to Permutive:

curl -XPOST https://api.permutive.com/v2.0/identify \
  -H 'X-API-Key: <PUBLIC_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "<PERMUTIVE_ID>",
    "aliases": [
      {
        "id": "<ADESTRA_CONTACT_ID>",
        "tag": "adestra",
        "priority": 0
      }
    ]
  }'

The tag value must match the Alias tag configured in the Permutive dashboard. You can retrieve your Public API Key from the Permutive dashboard.

Data Types

The Adestra integration activates cohort memberships to Adestra. Permutive sends cohort membership data to Adestra by adding and removing users from Contact lists.

Cohort Membership Data

Permutive sends user cohort memberships to Adestra by managing Contact list memberships via the Adestra API. The integration uses the Adestra Contact ID (configured via the Alias tag) to identify users.API Operations:When a user enters a cohort:

POST /contacts/{contact_id}/lists/{list_id} - Adds the user to the specified Contact list

When a user exits a cohort:

DELETE /contacts/{contact_id}/lists/{list_id} - Removes the user from the specified Contact list

string

The Adestra Contact ID for the user. This is Adestra’s internal identifier that you pass to Permutive via identity management.

string

The Adestra List ID of the Contact list to add/remove the user from. This is configured when you activate a cohort in the Permutive dashboard.

Identity Data Requirements

For the integration to work, Permutive must be able to match users with their Adestra Contact IDs. This requires implementing identity management.

string

required

The Adestra Contact ID for the user. This must be passed to Permutive using the identify method in the SDK or via the Identify API.

string

required

The identity type name. This must exactly match the “Alias tag” configured in the Permutive dashboard (defaults to adestra).

integer

required

The priority of this identifier. Set to 0 for most use cases.

Troubleshooting

Users not appearing in Adestra Contact lists

If users are not being added to Adestra Contact lists, verify the following:

Ensure you have implemented identity management correctly and are passing Adestra Contact IDs to Permutive
Verify that the “Alias tag” configured in the Permutive dashboard matches the tag value you’re using in identity management calls
Check that the Adestra List ID is correct when activating cohorts
Confirm that the Adestra API key is valid and has the correct permissions to manage contacts and lists
Verify that the Contact lists exist in Adestra before activating cohorts (the integration will not create lists automatically)
Check the Permutive Events page to ensure identity events are being collected with Adestra Contact IDs

Invalid API key error

If you receive an invalid API key error when setting up the integration:

Verify that you have copied the full API key from Adestra without any extra spaces or characters
Confirm that the API key has not expired or been revoked in Adestra
Check that the API key has the necessary permissions to access the Adestra API (specifically, permissions to manage contacts and lists)
Contact your Adestra account administrator if you’re unsure about API key permissions

Invalid List ID error

If you receive an error about an invalid List ID when activating a cohort:

Verify that you have entered the correct List ID from Adestra
Confirm that the Contact list still exists in Adestra and has not been deleted
Check that the API key has permission to access and manage the specified list
Ensure you’re using the List ID (numeric identifier) and not the list name

Delay in cohort updates

Cohort membership updates are processed in near real-time, typically within 10 seconds of a user entering or exiting a cohort. If you’re experiencing significant delays:

Check the Permutive Events page to ensure events are being collected properly
Verify that the integration is enabled and properly configured
Confirm that identity management is implemented correctly and Contact IDs are being passed to Permutive
Contact Permutive Support if delays persist beyond expected timeframes

Missing Contact IDs

If some users are not being synced to Adestra, it may be because their Contact IDs are not available in Permutive:

Verify that you’re calling identify with the Adestra Contact ID for all authenticated users
Check that the Contact ID is available before the user enters a cohort (identity must be established before cohort membership)
Review your identity management implementation to ensure Contact IDs are being passed consistently across all platforms (Web, iOS, Android, CTV)
Consider implementing server-side identity resolution if Contact IDs are only available in your backend systems

Adestra API rate limits

Adestra has API usage limits (10 concurrent connections). If you’re experiencing throttling or rate limit errors:

Contact Permutive Support to review your integration configuration
Consider reducing the number of cohorts synced to Adestra if you’re activating a very large number of cohorts
Review Adestra’s API documentation for current rate limits and usage restrictions

Changelog

For detailed changelog information, visit our Changelog.

Integrations

Identity

Contextual

Advertising

Marketing

Data Collaboration

Video

Social Media

Survey

Adestra

Adestra

Setup

Troubleshooting

Overview

Environment Compatibility

Prerequisites

Setup

Data Types

Troubleshooting

Changelog

​Adestra

Setup

Troubleshooting

​Overview

​Environment Compatibility

​Prerequisites

​Setup

​Data Types

​Troubleshooting

​Changelog

Adestra

Overview

Environment Compatibility

Prerequisites

Setup

Data Types

Troubleshooting

Changelog