> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knak

> Connect Knak to Conversion so emails built in Knak sync into Conversion as blasts or workflow emails.

The Knak integration connects your Knak instance to Conversion as a custom marketing automation platform (MAP). When a user syncs an email asset in Knak, Conversion pulls the asset's content and creates or updates an email in your workspace. The Knak asset is linked back to that email so later syncs update it in place.

## Before you start

* You need access to Knak Admin settings.
* You need the **Administrator** role in Conversion to save the integration settings.
* The Knak card appears under **Settings > Integrations** once the integration is enabled for your workspace. If you do not see it, contact your Conversion account team.

## Set up API access in Knak

<Steps>
  <Step title="Create an API role">
    1. Open Knak Builder and click **Admin** (top left).

    2. Click **Company > Roles > + Create Role**.

    3. Enter the role name **Conversion API User** and an optional description.

    4. Add the following permissions:

       | Permission group    | Permissions                                                                                                                                       |
       | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
       | **API Integration** | Add all: Allows API developers to read asset custom fieldsets, Can manage API tokens                                                              |
       | **Integrations**    | Allow the user to view merge tags, Allows the user to create, update, and delete merge tags, Allows the user to override merge tag default values |
       | **Sync**            | Add all: Resync assets, Sync assets, Sync assets that are not optimized, Sync unapproved assets                                                   |
       | **Emails**          | Download email, Send emails for review, Request Translations, Request Translations for Unapproved Email                                           |

    5. Click **Create**.
  </Step>

  <Step title="Create an API user">
    1. Click **Company > Users > Invite User**.
    2. Enter the user's email, first name, and last name.
    3. Select the API role you created.
    4. Click **Save User and Send Invite**.

    <Tip>
      Use an email alias when setting up integrations, for example `youremail+api@domain.com`. This keeps all integrations tied to one dedicated account and prevents disruptions if a team member leaves.
    </Tip>
  </Step>

  <Step title="Create an API key (Personal Access Token)">
    Conversion uses a permanent API key to read asset content from Knak. Sign in as the API user you created and generate the key at [https://enterprise.knak.io/account/api-access](https://enterprise.knak.io/account/api-access).

    <Warning>
      Knak shows the API key only once. Copy it and store it securely. You will enter it in Conversion later.
    </Warning>
  </Step>
</Steps>

## Create a webhook in Knak

Webhooks let events in Knak send an HTTP request to Conversion. The integration listens for the `asset.sync_requested` event, which tells Conversion to pull the asset's content. Any Knak user with permission to manage integrations can complete this step.

<Steps>
  <Step title="Copy your webhook URL from Conversion">
    In Conversion, go to **Settings > Integrations** and click **Set up** on the Knak card. Copy the **Webhook URL** shown at the top of the dialog. The URL is unique to your workspace and has the form:

    ```text theme={null}
    https://emailapi.conversion.ai/api/v1/businesses/<your-workspace-id>/knak/webhook
    ```
  </Step>

  <Step title="Add the webhook in Knak">
    1. Open Knak Builder and click **Admin** (top left).
    2. Navigate to **Integrations > Webhooks**.
    3. Enter the following values:

       | Field                 | Value                                                                      |
       | --------------------- | -------------------------------------------------------------------------- |
       | **Name**              | Conversion Sync                                                            |
       | **Payload URL**       | The webhook URL you copied from Conversion                                 |
       | **Secret**            | A secret of your choosing. Copy it, you will enter it in Conversion later. |
       | **Subscribed Events** | Select events > `asset.sync_requested`                                     |
  </Step>
</Steps>

## Create a custom MAP integration in Knak

Adding an integration lets Knak users sync assets to Conversion from the publish menu.

<Steps>
  <Step title="Add a new integration">
    1. Open Knak Builder and click **Admin** (top left).
    2. Navigate to **Integrations > Platforms > + Add New Integration**.
    3. Under **Custom Marketing Automation Platform**, click **Connect**.
  </Step>

  <Step title="Configure the integration">
    1. Enter the integration name **Conversion**.
    2. Set **Asset Sync Types** to **Email**.
    3. Set **Merge Tag Platform Format** to **None**.
    4. Click **Create New Integration**.
  </Step>
</Steps>

At this point you should have:

1. A role and API user in Knak
2. A webhook named **Conversion Sync** in your Knak instance
3. A custom MAP integration named **Conversion** in your Knak instance
4. An API key (Personal Access Token) that you copied
5. A webhook secret that you copied

## Connect Knak in Conversion

Navigate to **Settings > Integrations** and click **Set up** on the Knak card. Enter the **webhook secret** and the **API key** from the steps above, then click **Connect**.

Once connected, Knak appears with a green **Connected** badge. Administrators can update the secret or API key at any time from the settings icon on the card.

## How synced assets appear in Conversion

When a Knak user syncs an email asset to the Conversion integration, Conversion fetches the asset's HTML, subject, preview text, and sender details and creates an email in your workspace.

### Blasts by default

Knak emails sync as [blasts](/product-docs/emails/blasts/overview) by default. Conversion creates a draft blast with no recipients. Open the blast in Conversion to choose an audience and send it.

### Syncing as a workflow email

To sync an asset as a [workflow email](/product-docs/emails/workflow-emails/overview) instead, add `<WORKFLOW>` anywhere in the asset's name in Knak. For example, an asset named `Onboarding Day 1 <WORKFLOW>` syncs as a workflow email named **Onboarding Day 1**.

The marker is not case-sensitive and is removed from the email's name in Conversion. The email is then ready to use in a [Send Email](/product-docs/workflows/nodes/send-email) workflow node.

<Note>
  The `<WORKFLOW>` marker only affects the first sync of an asset. Once an asset is linked to an email, re-syncing updates that email's content and does not change whether it is a blast or a workflow email.
</Note>

### Re-syncing

Each Knak asset is linked to exactly one Conversion email. Re-syncing an asset updates the linked email's draft content in place. The email keeps its topic and theme settings.

### Linking an asset to an existing email

To sync a Knak asset into an email that already exists in Conversion, name the asset with that email's ID. Open the email in Conversion, open the options menu, and click **Copy ID**. Paste the ID as the asset's name in Knak and sync. The asset's content is written onto that email, and the email keeps its existing name.

### Senders

Conversion matches the asset's from address and reply-to address to your existing [senders](/product-docs/workspace-settings/emails-and-domains/senders). If no sender matches, the sender field is left empty on the synced email, and you can set it in Conversion before sending. Conversion never creates senders from a sync.

## Troubleshooting

* **Sync fails in Knak.** Confirm the webhook secret in Conversion matches the secret on the Knak webhook, and that the API key belongs to a user with the API role above.
* **Asset does not appear in Conversion.** Confirm the Knak webhook is subscribed to `asset.sync_requested` and its payload URL matches the webhook URL shown in Conversion.