Iterable

Iterable is a lifecycle platform connector. GenieOS keeps template editing, schema contracts, approvals, and send orchestration; Iterable receives triggered campaigns so lifecycle teams can keep downstream reporting and audience behaviour in Iterable.

Before you start

• Create a server-side Iterable API key.
• Confirm whether the project is in the US or EU Iterable data center.
• Decide which Iterable message type IDs should be used for transactional and marketing sends.
• Decide whether GenieOS should upsert a thin Iterable profile when a recipient does not already exist.

Setup

sequenceDiagram
  participant Admin as Workspace admin
  participant MG as GenieOS
  participant Iterable as Iterable
  participant Recipient as Recipient

  Admin->>Iterable: Create server-side API key
  Admin->>MG: Install Iterable connector
  MG->>Iterable: Upsert shadow template
  MG->>Iterable: Create or reuse triggered campaign
  MG->>Iterable: Target recipient with metadata
  Iterable->>Recipient: Deliver email
  Iterable->>MG: Event webhook with GenieOS send ID

1. Open Settings -> Connectors and choose Iterable.
2. Paste the server-side API key and choose the data center.
3. Enter message type IDs for transactional and marketing mail where needed.
4. Copy the webhook URL and custom X-GenieOS-Webhook-Token value.
5. Add an Iterable system webhook for send, delivery, bounce, complaint, unsubscribe, open, and click events.
6. Send a connector test.

How GenieOS maps sends to Iterable

Iterable does not send arbitrary GenieOS HTML as a one-off message in the same way a transactional ESP does. GenieOS bridges that model by creating and caching a shadow Iterable template and triggered campaign for each GenieOS template fingerprint.

flowchart TD
  Template[GenieOS template] --> Fingerprint[Content fingerprint]
  Fingerprint --> Cache{Reusable Iterable campaign?}
  Cache -->|No| Upsert[Upsert Iterable template]
  Upsert --> Campaign[Create triggered campaign]
  Cache -->|Yes| Campaign
  Campaign --> Target[Call Iterable email target]
  Target --> Events[Iterable webhook events]
  Events --> Timeline[GenieOS timeline]

Capabilities

Webhooks and suppressions

Iterable webhooks should include GenieOS metadata so events can be reconciled back to the correct send. Because Iterable does not provide HMAC signing for this flow, GenieOS verifies the custom webhook token shown during connector setup. Production workspaces can also enforce an IP allowlist when configured.

Unsubscribes, complaints, and hard bounces are stored as GenieOS suppressions. If an Iterable all-list ID is configured, GenieOS-side manual or imported suppressions can also be pushed to Iterable.

Troubleshooting

• API test failures usually mean the key is not server-side, has the wrong permissions, or belongs to the wrong data center.
• recipient_unknown send failures mean Iterable requires a profile before targeting. Enable profile upsert on send if that matches your data policy.
• Missing event reconciliation usually means the webhook does not include the GenieOS metadata or the custom header token is wrong.
• Attachments are not supported through Iterable. Use hosted links instead.