Cleverpush

Send subscriber data and tags to Cleverpush for targeted push notification campaigns across web and mobile. Sync subscription attributes and manage tag-based segmentation from your warehouse to Cleverpush channels.

Prerequisites

• A Cleverpush account with at least one channel configured
• A private API key with write access to subscriptions and tags
• Your Cleverpush channel ID (found in Channel Settings > API)

Permissions

To sync data to Cleverpush, your API key needs the following permissions:

• Subscriptions: Read and write access to create, update, and remove subscriptions
• Tags: Read and write access to assign and remove tags from subscriptions

Authentication

Cleverpush uses API key authentication for server-to-server access.

API Key

1. Log in to the Cleverpush dashboard 
2. Navigate to Channels and select your channel
3. Go to Settings > API
4. Copy your Private API Key
5. In Zeotap, paste the API key into the API Key field

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Subscriptions (Attributes)

subscription_id, email, phone, topics, country, language

Tags

subscription_id, tags

How It Works

Subscription Sync

When syncing subscription attributes, Zeotap sends individual sync requests to the Cleverpush API for each subscriber:

1. Each row in your model is mapped to a subscription identified by subscription_id
2. The subscription_id is sent as the user_id custom attribute for subscriber lookup
3. Known fields like email, phone, and topics are mapped to their corresponding Cleverpush fields
4. All other mapped fields are sent as custom attributes
5. Requests are sent to POST /subscription/sync with the channel ID and subscriber data
6. If a subscription with the given user_id already exists, it is updated; otherwise a new subscription is created
7. In remove mode, subscriptions are unsubscribed via POST /subscription/unsubscribe using the native subscriptionId

Note: Tag sync operations and unsubscribe require the native CleverPush subscriptionId (not an external user ID). Map your warehouse column containing CleverPush subscription IDs to the subscription_id field.

Tags

When syncing tags, Zeotap sends individual tag operations per subscription:

1. Tags are extracted from the tags field — comma-separated strings are split into individual tags
2. Add operations use POST /subscription/tag/add with the subscriptionId, channelId, and tagId
3. Remove operations use POST /subscription/tag/remove with the same parameters
4. In mirror mode, removed rows trigger tag removal while other rows trigger tag addition

Error Handling

• Failed requests are retried up to 3 times with exponential backoff
• HTTP 429 (rate limit) responses are retried automatically with the server-specified delay
• Per-row errors are tracked and reported in sync run results

Rate Limits

Cleverpush does not publish hard rate limits for their API. The following best practices apply:

• Zeotap sends one API request per subscription for attribute syncs
• Tag operations are sent individually per subscription per tag
• Zeotap automatically handles HTTP 429 responses with retry and backoff
• If you experience timeouts, consider reducing your sync batch size or sync frequency

Best Practices

• Use tags for segmentation: Cleverpush recommends using tags rather than topics for automatic audience segmentation
• Create tags in advance: Tag IDs referenced in your data should match existing tags in your Cleverpush channel settings
• Map subscription IDs consistently: Use a stable external user identifier as subscription_id so that repeated syncs update existing subscriptions rather than creating duplicates
• Set up custom attributes first: Custom attributes must be created in your Cleverpush channel settings before they can be populated via the API
• Use topics sparingly: Topics are designed for user-facing newsletter preferences; use tags for backend segmentation logic

Troubleshooting

Authentication failed: invalid API key

Verify your private API key is correct. In Cleverpush, navigate to your channel’s Settings > API and confirm the key. Ensure you are using the private API key (not the public key) and that it has not been regenerated since you configured the destination.

Channel not found

The channel ID configured in Zeotap does not match any channel in your Cleverpush account. Navigate to Channel Settings > API in the Cleverpush dashboard and verify the channel ID. Channel IDs are case-sensitive.

Subscription sync returns errors but data looks correct

Ensure that any custom attributes you are syncing have been created in your Cleverpush channel settings first. The API may reject attributes that do not exist in the channel configuration. Navigate to Settings > Custom Attributes in your channel to create them.

Tags not appearing on subscriptions

Verify that the tag IDs you are syncing match existing tags in your Cleverpush channel. Tag IDs can be found in Channel Settings > Tags. Tags must be created in the Cleverpush dashboard before they can be assigned via the API.

Subscriptions not being created

The Cleverpush subscription sync endpoint requires either an email address, phone number, or push token to create a new subscription. If you are only sending custom attributes without any contact identifier, the subscription may not be created. Ensure your mapping includes at least one contact field (e.g., email or phone).

Rate limiting (HTTP 429)

Zeotap automatically retries rate-limited requests with exponential backoff. If you see persistent rate limit errors, reduce the frequency of your sync schedule. For high-volume syncs, consider splitting your audience into smaller segments and syncing them on staggered schedules.