# Fetch coupons in Emarsys

> In this tutorial, let's set up Emarsys to retrieve existing coupons from Talon.One and use them in an Emarsys campaign.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

To do so, we rely on the Emarsys-specific [Get coupon](/third-party-api#tag/Emarsys/operation/emarsys/getCoupon) endpoint.

## Talon.One requirements

- You have set up [an Application][App].
- Your Application contains [a running campaign][campaigns] with the **Coupons** feature
  [enabled](/docs/product/campaigns/settings/manage-campaign-features.md).
- You have [added coupons](/docs/product/campaigns/coupons/create-coupons.md) to the campaign.
:::important
The Emarsys-specific endpoint supports only [personal codes](/docs/product/campaigns/coupons/create-coupons.md#generate-a-personal-code)
at the moment.
:::

You can edit the default format of the coupon codes in
the campaign's <Settings className="icon" /> [**Settings**][coupon format] section.

[coupon format]: /docs/product/campaigns/coupons/coupon-page-overview#edit-coupon-format

## Emarsys requirements

- You have set up your Emarsys account.
- You have an active Emarsys campaign for which you want to use coupon codes.

In this tutorial, we'll use a **block-based email campaign**.

## Set up the integration

<StepsContainer>

### Create an API key in Talon.One

In the Campaign Manager, create an Emarsys-specific API key:

1. In your Application, click <Settings className="icon" /> **Settings** > **Integration API Keys**.
1. Click <Add className="icon" /> **Create API Key**.
1. In the **Create API Key** drawer, if you are asked for a key type, select **Production**.
1. In **Key name**, type a name to identify the key.
1. In **Key expiration date**, select a date.

   :::tip
   Avoid choosing expiration dates that fall at the end of the year or during other
   high-traffic periods.
   :::

1. In **Third-party integration**, select **Yes**.
1. From **Platform**, select **{props.partner}**.
1. Click **Create API Key**.
1. Click <Copy className="icon" /> to copy the key for use.

:::note
You cannot view or copy the API key after closing the drawer.
:::

### Create a connection in Emarsys

To retrieve a coupon code from Talon.One, we call the following endpoint:

```text title="POST Get coupon"
https://integration.talon.one/emarsys/customer_profiles/coupons
```

<Button variant="primary" size="l" href="/third-party-api#tag/Emarsys/operation/emarsys/getCoupon">
  See API docs
</Button>

To access this endpoint, create an External Content connection in Emarsys:

1. Sign in to your Emarsys account.
1. Open **Content** > **External Content**.
1. Click **Create Connection**.
1. In **Connection**, enter the following details:
   - **Name**: A descriptive name for the connection.
   - **API URL**: `https://integration.talon.one/emarsys/customer_profiles/coupons?deployment=YOUR_DEPLOYMENT_URL`,
   where `YOUR_DEPLOYMENT_URL` is the base URL of your Talon.One deployment, for example, `mycompany.europe-west1.talon.one`.
1. In **Authentication**, enter the following details:
   1. **Method**: **HTTP basic authentication**
   1. **User name**: `ApiKey-v1`
   1. **Password**: The Emarsys-specific API key you [created](#create-an-api-key-in-talonone).
1. In **Fields**, enter the following details:
   - **Reference Fields**:

      | Field name      | Value for testing                                                       |
      | --------------- | ----------------------------------------------------------------------- |
      | `integrationId` | A valid Talon.One customer integration ID. Example: `URNGV8294NV`.      |
      | `campaignId`    | The ID of the Talon.One campaign containing the coupons. Example: `34`. |

   - **Response Fields**: The Talon.One coupon attributes to retrieve.For example,
   add a `value` response field to retrieve the coupon code.
      :::note
      - For a list of supported attributes, see the `coupons` array of the
      [List customer data](/integration-api#tag/Customer-profiles/operation/getCustomerInventory) response.
      - You can also use [custom attributes](/docs/product/account/dev-tools/manage-attributes.md#create-a-custom-attribute)
      as response fields. Ensure that the custom attribute has its **Entity** set to **Coupon**.
      For example, you can create a custom attribute named `percentage_discount` in Talon.One,
      use it for your coupons, and include the attribute in the response.
      :::
1. To test the connection with the values provided, click **Test**.
1. If the test is successful, click **Save**.

### Create tokens in Emarsys

To use a coupon attribute in your Emarsys campaign, create a [personalization token](https://esl.emarsys.com/hc/en-us/articles/12279054632337-Tokens):

1. In Emarsys, open **Content** > **Personalization**.
1. Click **Create Token** and choose **External Content**.
1. In **Setup**, enter the following details:
   - **Name**: A descriptive name for the token.
   - (Optional) **Category**: Create or assign a category. This helps you organize your tokens.
   The categories are shown in the **Personalization** sidebar when [editing your campaign](#use-the-tokens-in-an-emarsys-campaign).
   - **External Content preset**: Create or assign a [preset](#external-content-presets).
   - **Field**: The coupon attribute to use in your Emarsys campaign. For example, to use the coupon code in your campaign, select `value`.
1. Click **Save**.

Repeat the above steps for every coupon attribute you want to use in your Emarsys campaign.

### Use the tokens in an Emarsys campaign

Now, we can use the tokens we created in a campaign:

1. Open your Emarsys campaign for editing.In this tutorial, we'll use a **block-based email campaign**.
1. Go to the **Content Creation** step of the campaign creation wizard.
1. In the editor sidebar, open **Personalization** and find your created tokens
   in the **Custom Tokens** section.
1. Drag the desired tokens into the content editor window.
1. To test your coupon attributes, use the **Testmail** feature.
1. Click **Finish Editing**.

:::note
When using the **Inbox Preview** feature, placeholders are displayed instead of the actual token values.
:::

[App]: /docs/product/applications/overview.md
[campaigns]: /docs/product/campaigns/overview.md

</StepsContainer>

## External Content presets

To manage recurring coupon requests to Talon.One, create an External Content preset and assign it to [your personalization token](#create-tokens-in-emarsys). See the [Emarsys docs](https://help.sap.com/docs/SAP_EMARSYS/f8e2fafeea804018a954a8857d9dfff3/fdf0b3af74c11014805bffc1fe88873a.html).

:::note example
Assume you want to retrieve coupons of a specific campaign in Talon.One. The ID of this campaign is `34`.
Also, you want to use the customer's email address as the unique identifier to retrieve coupon codes from Talon.One.

In this case, create the following preset and assign it to your token:

- **Name**: A descriptive name for the preset.
- **Connection**: The External Content connection you [created](#create-a-connection-in-emarsys).
- **Parameters**:

   | Name            | Type          | Value   |
   | --------------- | ------------- | ------- |
   | `integrationId` | Contact Field | `Email` |
   | `campaignId`    | Constant      | `34`    |
:::