# How to Integrate Retool with ConvertKit

- Tool: Retool
- Difficulty: Beginner
- Time required: 20 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to ConvertKit using a REST API Resource with your ConvertKit API secret as the api_secret URL parameter on every request. Point the resource at https://api.convertkit.com/v3 and build queries against the subscribers, sequences, forms, and tags endpoints to create a creator-focused email dashboard that tracks subscriber growth, sequence performance, and form conversion rates.

## Build a ConvertKit Creator Email Dashboard in Retool

ConvertKit is the email platform of choice for bloggers, course creators, newsletter writers, and online educators who prioritize subscriber-centric email automation. While ConvertKit's own interface is purpose-built for creators, operations and growth teams often need a more flexible view of subscriber data — one that can join ConvertKit subscriber records with course enrollment data, transaction history from Stripe, or community platform membership status. A Retool integration with ConvertKit's API enables this unified view.

ConvertKit's API is one of the simplest in the email marketing space: there is no OAuth dance, no token refresh process, and no complex header signatures. The API secret is passed as a URL parameter with every request, making initial setup fast enough to complete in under 20 minutes. The API exposes subscribers (with their tags, custom fields, and sequence memberships), email sequences (with subscriber counts and step-level stats), forms (with conversion rates and subscriber acquisition data), and tags (for audience segmentation).

The most valuable Retool use case for ConvertKit is a subscriber intelligence dashboard that combines API data with creator-specific analytics. For example, a Retool app might show all subscribers who purchased a specific product (from Stripe) but are not yet enrolled in the corresponding email sequence (from ConvertKit), enabling the creator to manually trigger sequence enrollment for missed subscribers. Or it might surface subscribers with high engagement scores who have not yet been tagged as 'potential affiliate' — helping the creator identify partnership opportunities from their existing audience.

## Before you start

- A ConvertKit account (Creator or Creator Pro plan for full API access)
- Your ConvertKit API secret from Account Settings → Advanced → API Secret
- A Retool account with permission to create Resources
- Basic familiarity with REST API concepts (base URLs, URL parameters)
- Knowledge of your ConvertKit account's key data objects: sequences, forms, and tags used in your setup

## Step-by-step guide

### 1. Locate your ConvertKit API secret

ConvertKit uses a single API secret for authentication — there is no OAuth application to configure and no token expiry to manage. To find your API secret, log in to your ConvertKit account and navigate to Account Settings → Advanced. You will see an API Secret section with your secret displayed (or a button to reveal it). Copy the API secret value. This is a long alphanumeric string that should be treated like a password — it grants full access to your ConvertKit account via the API. Do not share it publicly or commit it to code repositories. You will also see an API Key on this page — the API Key is used only for read-only public operations like listing forms. The API Secret is required for all subscriber write operations (adding tags, subscribing, unsubscribing) and for accessing subscriber-level data. For your Retool integration, you will use the API Secret. Immediately store this value in a Retool Configuration Variable: in Retool, navigate to Settings → Configuration Variables, click Add Variable, name it CONVERTKIT_API_SECRET, paste the value, and check the 'Is Secret' checkbox to prevent it from being exposed in query logs or the frontend. Save the configuration variable before continuing to the resource setup step.

**Expected result:** Your ConvertKit API secret is copied and stored as a secret Configuration Variable named CONVERTKIT_API_SECRET in Retool Settings.

### 2. Configure the REST API Resource in Retool

In Retool, navigate to the Resources tab using the plug icon in the left sidebar or via the top navigation bar. Click Add Resource and select REST API from the resource type options. Name the resource 'ConvertKit API'. Set the Base URL to https://api.convertkit.com/v3. ConvertKit's authentication works by appending api_secret as a URL parameter to every request rather than using an Authorization header. To configure this, scroll to the URL Parameters section in the resource configuration and add a default URL parameter: Parameter Name → api_secret, Value → {{ retoolContext.configVars.CONVERTKIT_API_SECRET }}. This ensures every query sent through this resource automatically includes the API secret as a URL parameter without you having to add it manually to each individual query. Also add a second default URL parameter: api_key → {{ retoolContext.configVars.CONVERTKIT_API_KEY }} — some ConvertKit read-only endpoints require the API key rather than the secret, so having both pre-configured makes query creation easier. Do not add the API secret as a header — ConvertKit's API specifically expects it as a URL parameter. Click Save Resource. Test the connection by creating a query with Method GET and Path /subscribers — a successful response confirms the resource is correctly configured.

**Expected result:** The ConvertKit API resource is saved with the api_secret URL parameter configured. A test GET request to /subscribers returns your account's subscriber list.

### 3. Build subscriber queries with search and filtering

Create the subscriber management queries for your dashboard. First, create a query named 'getSubscribers'. Set Method to GET and Path to /subscribers. Add URL parameters: page → {{ pagination.page || 1 }} (ConvertKit uses 1-indexed pagination), sort_field → created_at, sort_order → desc. ConvertKit returns 50 subscribers per page by default. The response object contains subscribers (an array of subscriber objects), total_subscribers (integer), page (current page), total_pages (total page count). Create a transformer to normalize the subscriber data. Each subscriber has: id, email_address, first_name, state (active, unsubscribed, bounced, complained), created_at, and fields (custom fields as a key-value object). The transformer flattens custom fields into named columns so they display correctly in Retool's Table. For email search, create a separate query named 'searchSubscriberByEmail'. Set Method to GET, Path to /subscribers, and add URL parameter email_address → {{ emailSearchInput.value }}. ConvertKit's email search on the subscribers endpoint returns the matching subscriber or an empty array. For tag-based filtering, create a query named 'getSubscribersByTag'. Set Method to GET and Path to /tags/{{ tagFilter.value }}/subscriptions. Add URL parameters: page → {{ pagination.page || 1 }}, subscriber_state → Active. This endpoint returns only subscribers with the specified tag who are in the active state.

```
// Transformer: normalize ConvertKit subscribers
const subscribers = data.subscribers || [];
return subscribers.map(sub => ({
  id: sub.id,
  email: sub.email_address,
  first_name: sub.first_name || '',
  state: sub.state,
  created: new Date(sub.created_at).toLocaleDateString(),
  // Flatten custom fields
  ...Object.fromEntries(
    Object.entries(sub.fields || {}).map(([key, val]) => [
      'field_' + key, val || ''
    ])
  )
}));
```

**Expected result:** The getSubscribers query returns paginated subscriber records with status and custom fields, and the email search query returns a specific subscriber when a valid email is entered.

### 4. Build sequence, form, and tag analytics queries

Create queries for the analytics section of your dashboard. Create a query named 'getSequences'. Set Method to GET and Path to /sequences. This returns all email sequences in your account with their id, name, hold (whether the sequence is paused), repeat (whether subscribers can repeat), and created_at. Create a query named 'getForms'. Set Method to GET and Path to /forms. The response includes form id, name, type (hosted, inline, modal, slide_in), format, embed_js, embed_url, archived status, and subscriber counts. Create a query named 'getTags'. Set Method to GET and Path to /tags. This returns all tags with their id, name, and created_at. For subscriber counts per tag (not included in the tags list), create a JavaScript transformer that computes totals from the getSubscribersByTag query results, or accept that exact counts require individual requests per tag and display the tag list without counts for the initial view. Create a transformer named 'formatForms' for the forms query that computes useful display values from the raw data: humanize the form type name (capitalize and add spaces), flag archived forms with a label, and sort forms by subscriber count descending so the highest-converting forms appear at the top of the list.

```
// Transformer: format ConvertKit forms with enriched display data
const forms = data.forms || [];
const TYPE_LABELS = {
  hosted: 'Hosted Page',
  inline: 'Inline',
  modal: 'Modal Popup',
  slide_in: 'Slide-In'
};
return forms
  .filter(form => !form.archived)
  .map(form => ({
    id: form.id,
    name: form.name,
    type: TYPE_LABELS[form.type] || form.type,
    total_subscribers: form.total_subscriptions || 0,
    active_subscribers: form.active_subscriptions || 0,
    status: form.archived ? 'Archived' : 'Active'
  }))
  .sort((a, b) => b.total_subscribers - a.total_subscribers);
```

**Expected result:** The getSequences, getForms, and getTags queries return comprehensive lists of all ConvertKit account assets with relevant metadata for display in Retool Table components.

### 5. Assemble the creator dashboard UI and add subscriber actions

Build the complete dashboard using Retool's component library. Organize the app into two tabs using a Tab component: 'Subscribers' and 'Analytics'. In the Subscribers tab: add a Text Input named 'emailSearchInput' with placeholder 'Search by email address', a Select component named 'tagFilter' populated with getTags.data (value = tag id, label = tag name), and a Table named 'subscribersTable' bound to getSubscribers.data. Configure the state column with conditional tag formatting: green for 'active', red for 'unsubscribed', orange for 'bounced'. Add row actions: 'View Details' (opens a Modal showing the full subscriber profile), 'Unsubscribe' (triggers a DELETE /subscribers/{id}/unsubscribe query with a confirmation modal). For tag management, in the subscriber detail Modal add a multi-select component for tag assignment. Create queries: 'addTagToSubscriber' (POST /tags/{tagId}/subscriptions, body { email: subscribersTable.selectedRow.email }) and 'removeTagFromSubscriber' (DELETE /subscribers/{id}/tags/{tagId}). In the Analytics tab: add a Stat bar at the top showing total subscriber count from getSubscribers.data total_subscribers. Below, place a Table of sequences on the left and a Table of forms on the right. Add a Bar Chart below the forms table showing subscribers per form — use getForms.data as the dataset with name as the X axis and total_subscribers as the Y axis. Run all four base queries on page load.

```
// Query config: subscribe a user to a tag
// POST /tags/{tagId}/subscriptions
{
  "email": "{{ subscribersTable.selectedRow.email }}",
  "first_name": "{{ subscribersTable.selectedRow.first_name }}"
}
```

**Expected result:** A two-tab creator dashboard provides subscriber management with search, tag control, and unsubscribe actions in the Subscribers tab, and sequence, form, and tag performance analytics in the Analytics tab.

## Best practices

- Store the ConvertKit API secret in a Retool Configuration Variable marked as 'secret' and reference it via retoolContext.configVars — never paste the raw secret value directly into the resource configuration field as visible plain text
- Use the api_secret parameter exclusively for write operations and subscriber data access; use the less-privileged api_key parameter for read-only public endpoints like form embed information to minimize exposure of your secret
- Configure the getSubscribers query with a state=active URL parameter so subscriber counts and tables match what creators see in ConvertKit's own interface, avoiding confusion about discrepant numbers
- Add confirmation modals to unsubscribe actions — ConvertKit unsubscribes are reversible via the API (POST /subscribers/{id}/unsubscribe does not permanently delete), but the action immediately stops all email delivery to that subscriber
- Use ConvertKit's built-in pagination (page parameter, 50 items per page) rather than attempting to fetch all subscribers in one request — large creator accounts can have hundreds of thousands of subscribers
- Combine ConvertKit tag data with custom field data in transformer output to build computed segments client-side — for example, flagging subscribers who have the 'customer' tag but lack the 'onboarded' tag for follow-up outreach
- For sequence analytics, create separate queries per sequence rather than trying to aggregate all sequence statistics in one call — ConvertKit's API returns sequence-level subscriber counts but not open/click rates, which must be viewed in the ConvertKit dashboard
- Run tag and sequence list queries once on page load and cache the results in Retool state variables rather than re-fetching them on every subscriber action — tags and sequences change infrequently and caching reduces unnecessary API calls

## Use cases

### Build a subscriber management panel with tag and sequence control

Create a Retool app that lists all ConvertKit subscribers with their email, name, tags, subscription date, and status. Allow team members to search by email or tag, view a subscriber's full profile including custom fields and sequence memberships, add or remove tags, and subscribe or unsubscribe individual contacts. This gives creators a faster alternative to ConvertKit's native interface for bulk subscriber management and manual tagging operations.

Prompt example:

```
Build a Retool subscriber manager for ConvertKit. A search bar filters by email. A tag multi-select filters by tag. Show results in a Table with email, first name, created at, tags, and state. On row selection, show a detail panel with all custom fields, sequences they are enrolled in, and buttons to Add Tag, Remove Tag, and Unsubscribe.
```

### Build a sequence and form performance analytics dashboard

Create a Retool analytics panel that shows all ConvertKit email sequences with subscriber counts and open rates, alongside all forms with their conversion rates and total subscribers acquired. Include a Chart comparing subscriber acquisition by form over the last 30 days. This gives the creator a single-screen view of what content and forms are driving the most subscriber growth and sequence engagement.

Prompt example:

```
Build a Retool analytics panel for ConvertKit. Show sequences in a Table with name, subscriber count, and completion rate. Show forms in a second Table with name, total subscribers, and conversion rate. Add a Bar Chart showing subscribers per form. Add a Stat component for total subscriber count.
```

### Build a tag-based audience segmentation panel for targeted outreach

Create a Retool panel that lists all ConvertKit tags with subscriber counts and allows the team to view all subscribers under a specific tag. Include a bulk-action workflow for adding a tag to multiple subscribers selected in the Table, and a filter to find subscribers who have a specific tag but not another tag — enabling precise audience segmentation for targeted broadcast emails.

Prompt example:

```
Build a Retool segmentation panel for ConvertKit. Show all tags in a Table with name and subscriber count. On tag selection, load subscribers with that tag into a second Table. Include a Bulk Add Tag button that applies a selected tag to all checked rows. Add a filter for subscribers who have Tag A but not Tag B.
```

## Troubleshooting

### 401 Unauthorized on all ConvertKit API requests

Cause: The api_secret URL parameter is missing, incorrect, or the API secret has been regenerated in ConvertKit since the resource was configured, invalidating the stored value.

Solution: Open the Retool resource settings and verify that the api_secret URL parameter references the correct Configuration Variable. Go to ConvertKit Account Settings → Advanced and confirm the API secret matches what is stored in the Configuration Variable. If the secret has been regenerated, update the Configuration Variable with the new value. Avoid having trailing spaces in the pasted API secret value — these cause silent authentication failures.

### Subscriber search returns no results even for valid email addresses

Cause: ConvertKit's email_address search parameter requires an exact match — partial email searches are not supported. Searching for 'john' instead of 'john@example.com' will return an empty array.

Solution: Ensure the email search input is populated with a complete, valid email address before running the search query. Add a note or placeholder text to the search input that says 'Enter full email address to search'. For partial search functionality, fetch all subscribers across pages and filter the results client-side in a JavaScript transformer using a .includes() comparison on the email field.

### Total subscriber count shown in stats differs from count in ConvertKit dashboard

Cause: ConvertKit's subscriber count in the API includes subscribers in all states (active, unsubscribed, bounced, complained), while the ConvertKit dashboard typically shows only active subscribers by default.

Solution: Add a state=active URL parameter to your getSubscribers query to filter to active subscribers only, matching the ConvertKit dashboard's default count. Alternatively, display the total_subscribers field from the API response in a separate stat and add a note clarifying that it includes all subscriber states. The active-only count is the more meaningful metric for marketing operations.

### Adding a tag to a subscriber fails with 422 Unprocessable Entity

Cause: The tag subscription endpoint requires the subscriber's email address in the request body, not their ID. Passing the subscriber ID instead of the email causes a 422 error.

Solution: Verify that the addTagToSubscriber query body uses email (the subscriber's email_address field from the table row) and not id. The POST /tags/{tagId}/subscriptions endpoint accepts an email field in the JSON body. Check that the subscribersTable.selectedRow.email references the correct column name from your transformer output — if you renamed the column to 'email_address' in the transformer, update the query body reference accordingly.

```
// Correct tag subscription body
{
  "email": "{{ subscribersTable.selectedRow.email }}"
}
```

## Frequently asked questions

### Does Retool have a native ConvertKit connector?

No, Retool does not have a native ConvertKit connector. You connect via a REST API Resource using ConvertKit's simple API secret URL parameter authentication. The setup takes about 20 minutes and provides access to all ConvertKit API endpoints including subscribers, sequences, forms, and tags. ConvertKit's straightforward authentication model makes it one of the easiest email platforms to connect to Retool.

### Do ConvertKit API secrets expire?

ConvertKit API secrets do not expire automatically — they remain valid until you manually regenerate them from Account Settings → Advanced. Unlike OAuth tokens, there is no scheduled refresh process to manage. However, you should regenerate your API secret immediately if you suspect it has been exposed. After regenerating, update the value in your Retool Configuration Variable to restore the integration.

### Can I add subscribers to ConvertKit sequences from Retool?

Yes. Use POST /sequences/{sequence_id}/subscriptions with a JSON body containing the subscriber's email address. This enrolls the subscriber in the sequence starting from the first email. In Retool, create a query for this endpoint triggered by a 'Enroll in Sequence' button in the subscriber detail view, with a Select component for the sequence and a confirmation modal before executing.

### How do I get subscriber-level open and click data from ConvertKit in Retool?

ConvertKit's V3 API does not provide subscriber-level open or click event data — individual engagement events are not exposed through the API. The API provides aggregate statistics at the sequence and form level (total subscribers, conversion rates) but not per-subscriber email engagement history. For individual engagement data, you would need to use ConvertKit's native reporting interface or integrate with a third-party analytics tool via ConvertKit webhooks.

### Can I use the same Retool ConvertKit integration for multiple ConvertKit accounts?

Yes, create a separate REST API Resource in Retool for each ConvertKit account, each configured with that account's API secret in a separate Configuration Variable. In your Retool dashboard, use a Select component to switch between accounts, binding the active resource dynamically using Retool's resource switching feature. This is useful for agencies or teams managing multiple creator accounts in a single Retool workspace.

---

Source: https://www.rapidevelopers.com/retool-integrations/convertkit
© RapidDev — https://www.rapidevelopers.com/retool-integrations/convertkit