Marketing Integrations API

The Marketing Integrations API provides endpoints for managing mailing lists and SMS segments across marketing platforms.

Overview

Supported marketing platforms:

Klaviyo - Email marketing and automation
Maropost - Marketing automation platform
Attentive - SMS marketing platform

Each integration supports:

Fetching available lists/segments
Custom display name mappings (per brand)

Klaviyo Lists

Get Klaviyo Lists

Fetch available Klaviyo mailing lists with custom display names.

GET /api/admin/klaviyo/lists

Requires: Session cookie

Response

{
  "success": true,
  "lists": [
    {
      "listId": "abc123",
      "originalName": "Newsletter Subscribers",
      "displayName": "Main Newsletter"
    },
    {
      "listId": "def456",
      "originalName": "Product Updates",
      "displayName": "Product Updates"
    }
  ],
  "mappings": {
    "abc123": "Main Newsletter"
  },
  "count": 2
}

Not Configured Response

{
  "success": false,
  "error": "Klaviyo not configured. Please add your Private API Key.",
  "lists": [],
  "mappings": {}
}

Update Klaviyo List Names

Customize display names for Klaviyo lists.

PUT /api/admin/klaviyo/lists
Content-Type: application/json

Requires: Session cookie

Request Body

{
  "mappings": {
    "abc123": "Main Newsletter",
    "def456": ""
  }
}

Set an empty string to remove a custom name and use the original.

Response

{
  "success": true,
  "updated": 2
}

Maropost Lists

Get Maropost Lists

Fetch available Maropost mailing lists.

GET /api/admin/maropost/lists

Requires: Session cookie

Response

{
  "success": true,
  "lists": [
    {
      "listId": "12345",
      "originalName": "Main Subscribers",
      "displayName": "Customer List"
    }
  ],
  "mappings": {
    "12345": "Customer List"
  },
  "count": 1
}

Not Configured Response

{
  "success": false,
  "error": "Maropost not configured. Please add Account ID and API Key.",
  "lists": [],
  "mappings": {}
}

Update Maropost List Names

PUT /api/admin/maropost/lists
Content-Type: application/json

Requires: Session cookie

Request Body

{
  "mappings": {
    "12345": "Customer List"
  }
}

Response

{
  "success": true,
  "updated": 1
}

Attentive Segments

Get Attentive Segments

Fetch available Attentive SMS segments.

GET /api/admin/attentive/lists

Requires: Session cookie

Response

{
  "success": true,
  "lists": [
    {
      "listId": "seg_abc123",
      "originalName": "VIP Customers",
      "displayName": "VIP SMS List"
    },
    {
      "listId": "seg_def456",
      "originalName": "New Subscribers",
      "displayName": "New Subscribers"
    }
  ],
  "mappings": {
    "seg_abc123": "VIP SMS List"
  },
  "count": 2
}

Not Configured Response

{
  "success": false,
  "error": "Attentive not configured. Please add your API Key and Company ID.",
  "lists": [],
  "mappings": {}
}

Update Attentive Segment Names

PUT /api/admin/attentive/lists
Content-Type: application/json

Requires: Session cookie

Request Body

{
  "mappings": {
    "seg_abc123": "VIP SMS List"
  }
}

Response

{
  "success": true,
  "updated": 1
}

Environment Variables

Klaviyo

KLAVIYO_PRIVATE_API_KEY=pk_abc123...

Maropost

MAROPOST_ACCOUNT_ID=1234
MAROPOST_API_KEY=your-api-key
# or
MAROPOST_AUTH_TOKEN=your-auth-token

Maropost automatically selects the correct API endpoint based on your account ID:

Account IDs 5000+: api-ca1.maropost.com
Account IDs 4000-4999: api-eu1.maropost.com
Account IDs below 4000: api.maropost.com

Attentive

ATTENTIVE_API_KEY=your-api-key
ATTENTIVE_COMPANY_ID=your-company-id

Error Responses

Status	Error	Description
400	`Invalid mappings`	Mappings must be an object
400	`No brand context`	No brand in session
401	`Unauthorized`	Session required
500	`Failed to fetch lists`	API call failed

Code Example

Fetching and Displaying Lists

interface ListMapping {
  listId: string;
  originalName: string;
  displayName: string;
}

interface ListsResponse {
  success: boolean;
  lists: ListMapping[];
  mappings: Record<string, string>;
  count: number;
  error?: string;
}

async function fetchKlaviyoLists(): Promise<ListsResponse> {
  const response = await fetch('/api/admin/klaviyo/lists', {
    credentials: 'include',
  });
  return response.json();
}

async function updateListNames(
  provider: 'klaviyo' | 'maropost' | 'attentive',
  mappings: Record<string, string>
) {
  const response = await fetch(`/api/admin/${provider}/lists`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'include',
    body: JSON.stringify({ mappings }),
  });
  return response.json();
}

// Usage
const { lists } = await fetchKlaviyoLists();

// Display lists with custom names
lists.forEach((list) => {
  console.log(`${list.displayName} (${list.listId})`);
});

// Update a custom name
await updateListNames('klaviyo', {
  abc123: 'My Custom Name',
});

Use Cases

Checkout Form Integration

Use list IDs in checkout configuration to auto-subscribe customers:

{
  "orderId": "order_123",
  "metadata": {
    "klaviyoListId": "abc123",
    "attentiveSegmentId": "seg_def456"
  }
}

Analytics and Tracking

Subscribe customers post-purchase via webhooks:

// In your webhook handler
async function handleOrderConfirmed(order: Order) {
  if (order.metadata?.klaviyoListId) {
    await subscribeToKlaviyo(
      order.customer.email,
      order.metadata.klaviyoListId
    );
  }
}

Marketing Integrations

On this page