Postscript

Sync subscribers and events to Postscript for SMS marketing. Zeotap keeps your Postscript subscriber lists, tags, custom properties, and event data in sync with your warehouse.

Prerequisites

• A Postscript account with API access enabled
• A Postscript private API key (starts with sk_)
• At least one keyword configured in Postscript (required for subscriber creation)

Permissions

The Postscript API key must have permissions to:

• Create and update subscribers
• Manage compliance (unsubscribe) operations
• Create custom events
• Read keywords

Authentication

Postscript uses Private API Key authentication.

1. Log in to your Postscript account at app.postscript.io
2. Navigate to Account > API
3. Click Create Security Key Pair
4. Copy the Private API Key (starts with sk_)
5. Paste it into the Private API Key field in Zeotap

Important: Use the Private API Key, not the Public API Key. The private key is required for all server-side API operations.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

When Object Type = Subscriber

When Object Type = Event

Default Destination Fields

Subscriber fields: phone_number, email, tags, properties, shopify_customer_id

Event fields: type, phone_number, email, subscriber_id, occurred_at, external_id, properties

How It Works

Subscriber Sync

1. Zeotap reads rows from your warehouse model
2. Each row is sent individually to the Postscript Create Subscriber endpoint (POST /api/v2/subscribers)
3. New subscribers receive an opt-in confirmation SMS from Postscript
4. The create endpoint is idempotent for existing phone numbers, so upsert mode works natively
5. For remove (audience sync), rows are unsubscribed via PATCH /api/v2/compliance/unsubscribe

Event Sync

1. Zeotap reads rows from your warehouse model
2. Each row is sent to the Postscript Create Event endpoint (POST /api/v2/events)
3. Events are matched to subscribers asynchronously using subscriber_id, phone, or email
4. Events can trigger Postscript Flows and automation rules

Batch Processing

Postscript does not provide a bulk API, so rows are sent individually. Zeotap handles:

• Rate limiting: Automatic retry with exponential backoff on 429 responses
• Error handling: Per-row error tracking with detailed failure messages
• Retries: Up to 3 retries per request on transient failures (429, 5xx)

Rate Limits

Postscript enforces a rate limit of 15 requests per second per API key. Zeotap respects this limit and implements exponential backoff when rate limits are hit.

If you receive 429 errors in sync logs, the sync will automatically retry. For large subscriber lists, syncs may take longer due to rate limiting.

Best Practices

• Use E.164 phone format: Always include the country code (e.g. +15555555555) for reliable subscriber matching
• Set up keywords first: Create and configure your keywords in Postscript before running subscriber syncs
• Use tags for segmentation: Map a tags column to organize subscribers into Postscript segments
• Custom properties: Use the properties field to sync up to 50 custom key-value pairs per subscriber
• Event naming: Use consistent, descriptive event names with underscores (e.g. cart_abandoned, order_placed)
• Monitor opt-in rates: Not all created subscribers will confirm opt-in; monitor your Postscript dashboard

Troubleshooting

Invalid API key format

Postscript private API keys must start with sk_. If you see an authentication error, verify you are using the Private API Key (not the Public API Key) from your Postscript account settings.

Missing keyword_id or keyword

When syncing subscribers, you must configure either a Keyword ID or Keyword in the destination settings. Navigate to Keywords in Postscript to find your keyword details.

Subscribers not appearing in Postscript

New subscribers created via the API must confirm their opt-in before becoming active. Check the Pending subscribers list in Postscript. The subscriber will become active after confirming via SMS.

Phone number format errors

Postscript requires valid phone numbers. Use E.164 format (+15555555555) for best results. Numbers without country codes may be rejected.

Rate limit errors (429)

Zeotap automatically retries on rate limit errors with exponential backoff. If syncs are consistently slow, consider reducing the sync frequency or splitting large audiences into smaller batches.

Unsubscribe failing

The unsubscribe endpoint requires either a subscriber_id or phone_number. Ensure at least one of these fields is mapped in your sync configuration.

Events not triggering Flows

Events are matched to subscribers asynchronously. If an event references a subscriber that does not exist in Postscript, the event may be discarded. Ensure subscribers are synced before sending events.

Custom properties exceeding limit

Postscript allows up to 50 custom properties per subscriber. If you map more than 50 property keys, excess properties will be silently dropped by the API.