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

# Loops

> Add a bot to Loops using the official integration.

{/* vale on */}

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KMZANASVEZEW761JG63F1RM0)
*v0.1.5*

The official Loops integration allows your bot to send emails to your customers via Loops.

## Setup

> [!NOTE]
>
> You will need:
>
> * A [published bot](https://botpress.com/docs/get-started/quickstart)
> * A [Loops account](https://app.loops.so/)

### Step 1: Install the integration in Botpress

First, install the integration in Botpress:

**Step 1**

In Botpress Studio, select **Explore Hub** in the upper-right corner.

**Step 2**

Search for the **Loops** integration, then select **Install Integration**.

**Step 3**

In the **Configuration** menu, you should see two fields: **API Key** and **Webhook Signing Secret**. Leave these blank for now—you'll come back to them after configuring the integration in Loops.

**Step 4**

Copy the webhook URL.

### Step 2: Configure the webhook in Loops

Next, configure your Botpress webhook in Loops:

**Step 1**

Log in to your Loops account.

**Step 2**

Go to **Settings** > **Webhook**.

**Step 3**

Paste your integration's webhook URL into the **Endpoint URL** field, then select **Update URL**.

**Step 4**

Copy the generated **Signing Secret**.

**Step 5**

Paste it into the integration's **Webhook Signing Secret** field in Botpress.

### Step 3: Create a Loops API key

Then, create your Loops API key:

**Step 1**

In your Loops account, go to **Settings** > **API**.

**Step 2**

Select **Generate key**.

**Step 3**

Copy the generated key, then paste it into the integration's **API Key** field in Botpress.

> [!TIP]
>
> Your Loops integration is ready. You can use the integration's [Cards](#cards) and [Triggers](#triggers) to interact with your customer emails.

***

## Cards

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Send Transactional Email

Send a transactional email to a client

**input** `object`

**email** `string` *required*

The email address of the recipient.

**transactionalId** `string` *required*

The ID of the transactional email to send.

**dataVariables** `array` *required*

An object containing data as defined by the data variables added to the transactional email template.

**array item properties**

**key** `string` *required*

The key of the data variable

**value** `string` *required*

The value of the data variable

**addToAudience** `boolean`

If true, a contact will be created in your audience using the email value (if a matching contact doesn’t already exist).

**idempotencyKey** `string`

Optionally send an idempotency key to avoid duplicate requests. The value should be a string of up to 100 characters and should be unique for each request. We recommend using V4 UUIDs or some other method with enough guaranteed entropy to avoid collisions during a 24 hour window. The endpoint will return a 409 Conflict response if the idempotency key has been used in the previous 24 hours.

**fileIds** `array`

The Botpress client-generated IDs of the files to be attached to the email. They must have already been uploaded to your bot via the Files API. The name of the file will be used as the filename of the attachment. Use this for a list of templates the user can choose from.

**fileData** `array`

The name, base64-encoded data, and MIME content type of custom files to be attached to the email.

**array item properties**

**filename** `string` *required*

The name of the file

**contentType** `string` *required*

The MIME content type of the file

**data** `string` *required*

The base64-encoded data of the file

**output** `object`

This Card has no output.

## Triggers

{/* vale off */}

Here's a reference for all [Triggers](https://botpress.com/docs/studio/concepts/triggers.md) available with the integration:

> [!TIP]
>
> You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.

### Email Clicked

Sent when a link in a campaign or loop email is clicked. This event is not available for transactional emails because link clicks are not tracked in transactional emails.

**payload** `object`

**eventName** `string` *required*

The type of event as defined by Loops

**webhookSchemaVersion** `string` *required*

Will be 1.0.0 for all events

**eventTime** `number` *required*

The Unix timestamp of the time the event occurred

**contactIdentity** `object` *required*

The identifiers of the contact. Includes the contact ID, email address, and user ID

**id** `string` *required*

The ID of the contact assigned by Loops

**email** `string` *required*

The email address of the contact

**userId** `string | null` *required*

The unique user ID created by the contact. May be null

**email** `object` *required*

The details about an individual email sent to a recipient. Includes the email ID, the ID of the sent version, and the subject

**id** `string` *required*

The ID of the email

**emailMessageId** `string` *required*

The ID of the sent version of the email

**subject** `string` *required*

The subject of the sent version of the email

**sourceType** `enum\<string\>` *required*

The type of email that triggered the event. One of campaign or loop

Available options: `campaign`, `loop`

**campaignId** `string`

The ID of the campaign email. Only one of Campaign ID or Loop ID must exist.

**loopId** `string`

The ID of the loop email. Only one of Campaign ID or Loop ID must exist.

### Email Delivered

Sent when an email is delivered to its recipient.

**payload** `object`

**eventName** `string` *required*

The type of event as defined by Loops

**webhookSchemaVersion** `string` *required*

Will be 1.0.0 for all events

**eventTime** `number` *required*

The Unix timestamp of the time the event occurred

**contactIdentity** `object` *required*

The identifiers of the contact. Includes the contact ID, email address, and user ID

**id** `string` *required*

The ID of the contact assigned by Loops

**email** `string` *required*

The email address of the contact

**userId** `string | null` *required*

The unique user ID created by the contact. May be null

**email** `object` *required*

The details about an individual email sent to a recipient. Includes the email ID, the ID of the sent version, and the subject

**id** `string` *required*

The ID of the email

**emailMessageId** `string` *required*

The ID of the sent version of the email

**subject** `string` *required*

The subject of the sent version of the email

**sourceType** `enum\<string\>` *required*

The type of email that triggered the event. One of campaign, loop, or transactional

Available options: `campaign`, `loop`, `transactional`

**campaignId** `string`

The ID of the campaign email. Only one of Campaign ID or Loop ID must exist.

**loopId** `string`

The ID of the loop email. Only one of Campaign ID or Loop ID must exist.

**transactionalId** `string`

The ID of the transactional email. Only one of Campaign ID, Loop ID, or Transactional ID must exist.

### Email Hard Bounced

Sent when an email hard bounces. Hard bounces are persistent email delivery failures, for example a mailbox that doesn't exist. The email will not be delivered.

**payload** `object`

**eventName** `string` *required*

The type of event as defined by Loops

**webhookSchemaVersion** `string` *required*

Will be 1.0.0 for all events

**eventTime** `number` *required*

The Unix timestamp of the time the event occurred

**contactIdentity** `object` *required*

The identifiers of the contact. Includes the contact ID, email address, and user ID

**id** `string` *required*

The ID of the contact assigned by Loops

**email** `string` *required*

The email address of the contact

**userId** `string | null` *required*

The unique user ID created by the contact. May be null

**email** `object` *required*

The details about an individual email sent to a recipient. Includes the email ID, the ID of the sent version, and the subject

**id** `string` *required*

The ID of the email

**emailMessageId** `string` *required*

The ID of the sent version of the email

**subject** `string` *required*

The subject of the sent version of the email

**sourceType** `enum\<string\>` *required*

The type of email that triggered the event. One of campaign, loop, or transactional

Available options: `campaign`, `loop`, `transactional`

**campaignId** `string`

The ID of the campaign email. Only one of Campaign ID or Loop ID must exist.

**loopId** `string`

The ID of the loop email. Only one of Campaign ID or Loop ID must exist.

**transactionalId** `string`

The ID of the transactional email. Only one of Campaign ID, Loop ID, or Transactional ID must exist.

### Email Opened

Sent when a campaign or loop email is opened. This event is not available for transactional emails because email opens are not tracked for transactional emails.

**payload** `object`

**eventName** `string` *required*

The type of event as defined by Loops

**webhookSchemaVersion** `string` *required*

Will be 1.0.0 for all events

**eventTime** `number` *required*

The Unix timestamp of the time the event occurred

**contactIdentity** `object` *required*

The identifiers of the contact. Includes the contact ID, email address, and user ID

**id** `string` *required*

The ID of the contact assigned by Loops

**email** `string` *required*

The email address of the contact

**userId** `string | null` *required*

The unique user ID created by the contact. May be null

**email** `object` *required*

The details about an individual email sent to a recipient. Includes the email ID, the ID of the sent version, and the subject

**id** `string` *required*

The ID of the email

**emailMessageId** `string` *required*

The ID of the sent version of the email

**subject** `string` *required*

The subject of the sent version of the email

**sourceType** `enum\<string\>` *required*

The type of email that triggered the event. One of campaign or loop

Available options: `campaign`, `loop`

**campaignId** `string`

The ID of the campaign email. Only one of Campaign ID or Loop ID must exist.

**loopId** `string`

The ID of the loop email. Only one of Campaign ID or Loop ID must exist.

### Email Soft Bounced

Sent when an email soft bounces. Soft bounces are temporary email delivery failures, for example a connection timing out. Soft bounces are retried multiple times and some times the email is delivered.

**payload** `object`

**eventName** `string` *required*

The type of event as defined by Loops

**webhookSchemaVersion** `string` *required*

Will be 1.0.0 for all events

**eventTime** `number` *required*

The Unix timestamp of the time the event occurred

**contactIdentity** `object` *required*

The identifiers of the contact. Includes the contact ID, email address, and user ID

**id** `string` *required*

The ID of the contact assigned by Loops

**email** `string` *required*

The email address of the contact

**userId** `string | null` *required*

The unique user ID created by the contact. May be null

**email** `object` *required*

The details about an individual email sent to a recipient. Includes the email ID, the ID of the sent version, and the subject

**id** `string` *required*

The ID of the email

**emailMessageId** `string` *required*

The ID of the sent version of the email

**subject** `string` *required*

The subject of the sent version of the email

**sourceType** `enum\<string\>` *required*

The type of email that triggered the event. One of campaign, loop, or transactional

Available options: `campaign`, `loop`, `transactional`

**campaignId** `string`

The ID of the campaign email. Only one of Campaign ID or Loop ID must exist.

**loopId** `string`

The ID of the loop email. Only one of Campaign ID or Loop ID must exist.

**transactionalId** `string`

The ID of the transactional email. Only one of Campaign ID, Loop ID, or Transactional ID must exist.

### Email Spam Reported

Sent when a recipient reports your email as spam.

**payload** `object`

**eventName** `string` *required*

The type of event as defined by Loops

**webhookSchemaVersion** `string` *required*

Will be 1.0.0 for all events

**eventTime** `number` *required*

The Unix timestamp of the time the event occurred

**contactIdentity** `object` *required*

The identifiers of the contact. Includes the contact ID, email address, and user ID

**id** `string` *required*

The ID of the contact assigned by Loops

**email** `string` *required*

The email address of the contact

**userId** `string | null` *required*

The unique user ID created by the contact. May be null

**email** `object` *required*

The details about an individual email sent to a recipient. Includes the email ID, the ID of the sent version, and the subject

**id** `string` *required*

The ID of the email

**emailMessageId** `string` *required*

The ID of the sent version of the email

**subject** `string` *required*

The subject of the sent version of the email

**sourceType** `enum\<string\>` *required*

The type of email that triggered the event. One of campaign, loop, or transactional

Available options: `campaign`, `loop`, `transactional`

**campaignId** `string`

The ID of the campaign email. Only one of Campaign ID or Loop ID must exist.

**loopId** `string`

The ID of the loop email. Only one of Campaign ID or Loop ID must exist.

**transactionalId** `string`

The ID of the transactional email. Only one of Campaign ID, Loop ID, or Transactional ID must exist.

### Email Unsubscribed

Sent when a recipient unsubscribes via the unsubscribe link in an email. This event is not available for transactional emails because unsubscribe links are not included or required for transactional emails.

**payload** `object`

**eventName** `string` *required*

The type of event as defined by Loops

**webhookSchemaVersion** `string` *required*

Will be 1.0.0 for all events

**eventTime** `number` *required*

The Unix timestamp of the time the event occurred

**contactIdentity** `object` *required*

The identifiers of the contact. Includes the contact ID, email address, and user ID

**id** `string` *required*

The ID of the contact assigned by Loops

**email** `string` *required*

The email address of the contact

**userId** `string | null` *required*

The unique user ID created by the contact. May be null

**email** `object` *required*

The details about an individual email sent to a recipient. Includes the email ID, the ID of the sent version, and the subject

**id** `string` *required*

The ID of the email

**emailMessageId** `string` *required*

The ID of the sent version of the email

**subject** `string` *required*

The subject of the sent version of the email

**sourceType** `enum\<string\>` *required*

The type of email that triggered the event. One of campaign or loop

Available options: `campaign`, `loop`

**campaignId** `string`

The ID of the campaign email. Only one of Campaign ID or Loop ID must exist.

**loopId** `string`

The ID of the loop email. Only one of Campaign ID or Loop ID must exist.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.