Setup

Everything you need to configure before Clerk.io can send emails on your behalf.

This guide covers the setup needed before Clerk.io can send emails on your behalf.

It applies to campaigns, flows, and automated triggers like Abandoned Cart. If you only want to add personalised product recommendations to emails sent from Klaviyo, Mailchimp, or another platform, go to Embeds instead.

Each concept below explains what it does, when you need it, and how to manage it with Clerk.js or the API where code is required.

Choose the right setup path #

Use the section that matches the task you need to complete:

Check the setup: Open Setup Status to find missing configuration or broken tracking.
Send from your domain: Configure the Sender Domain and verify its DNS records.
Prepare recipients: Sync existing subscribers, import them, or collect new sign-ups.
Configure email sending: Set up Store Personalization, Email Designs, Email Identification, and Cart Tracking.

The setup is task-based. For example, Abandoned Cart requires email identification and cart tracking, while a one-off campaign requires a sender domain, subscribers, and an email design.

Setup Status #

The Setup Status tab gives you a live overview of your email setup.

Find it in Email > Configuration > Setup Status. It shows whether the required parts are configured, whether tracking is working, and whether emails are being sent as expected.

Each item has a coloured dot. Green means everything is in order, red means something is missing or broken, and orange is a warning worth checking.

The checks are grouped into three areas:

Configuration covers the core setup. This includes whether email sending is enabled, which sender domain is configured, how many subscribed recipients are available, and whether active flow steps have email designs.

On-site tracking shows whether visitor tracking is running. It also shows how many visitors or baskets have been linked to an email address in the last seven days.

Flows & sending shows whether active flows are configured, how many flow events are pending, how many emails have been sent recently, and whether the send queue is healthy.

Start here when emails are not sending as expected. It is the closest thing email setup has to a dashboard that quietly taps the fuel gauge.

Sender Domain #

How Clerk.io sends emails from your domain — a three-step overview of DNS setup

The sender domain is the domain Clerk.io uses when sending emails for your store.

Before Clerk.io can send from that domain, you need to authenticate it with DNS records. These records tell receiving mail servers that Clerk.io is allowed to send emails on your behalf.

Without this proof, emails can be rejected or sent to spam. Mail servers are suspicious by profession, and frankly they have seen things.

DNS Records #

Add the required DNS records in your domain host. This is usually where you manage your domain, such as Cloudflare, GoDaddy, Route 53, or a similar provider.

Clerk.io uses three types of DNS records:

SPF declares which services can send email from your domain.
DKIM adds a signature so recipients can verify the email came from you and was not changed in transit.
CNAME is used for tracking opens and clicks in your campaigns.

SPF records: A domain can only have one SPF TXT record. If you already have one, merge the directive, e.g. include:mailgun.org, into the existing record instead of creating a second one.

To find your records, go to Email > Configuration > Domain Setup and follow the guide for your hosting provider.

After entering your Sender Email and Sender Name, Clerk.io generates the exact record values. Add them to your domain host, then return to Email > Configuration > DNS Records and click Verify Now.

Subscribers #

A subscriber is an email address that has opted in to receive marketing emails.

Clerk.io needs subscribers before it can send campaigns. A flow can identify a visitor and know exactly what they browsed, but it still cannot send marketing email to someone who has not subscribed.

There are several ways to bring subscribers into Clerk.io:

Sync them from an existing email platform.
Import them from a CSV file.
Include them in your data feed with subscribed: true.
Collect new sign-ups from your website with a form.

Syncing Existing Subscribers #

Subscriber sync is the best option if you already have subscribers in a platform like Klaviyo or Mailchimp.

First, connect your email platform in Settings > Integrations. Then go to Email > Configuration > Sync Subscribers and enable the toggle for the integration.

Sync Subscribers tab in Email Configuration

To find the guide for a specific email platform, use the integrations menu in the sidebar and follow its Sync Data guide.

If you do not use an external email platform, import subscribers with a CSV file or include them in your data feed using subscribed: true on customer records.

Getting New Subscribers #

Getting new subscribers means collecting fresh sign-ups from your website.

This is different from syncing existing subscribers. Syncing brings in people who already opted in elsewhere. A sign-up form lets new visitors opt in directly from your store.

Use this if Clerk.io is your primary email platform, or if you want a form that subscribes visitors directly to Clerk.io.

Using Clerk.js #

Use Clerk.js when a visitor signs up directly on your website.

The example below subscribes the entered email address globally. You can place the form in a footer, on a homepage, or in a popup, then style it to match your store.

<div class="clerk-sign-up">
   <h2 class="clerk-sign-up-headline">Sign up now!</h2>
   <div class="clerk-sign-up-subtitle">Get personal offers and stay up-to-date with trends.</div>
   <div class="clerk-input-wrapper">
      <input type="text" id="clerk-add-subscriber-input" placeholder="Enter your email">
      <button id="clerk-add-subscriber-btn" onclick="add_subscriber()">Subscribe</button>
   </div>
   <div id="clerk-subscribe-message"></div>
</div>

<script>
   function add_subscriber() {
      var clerk_btn = document.getElementById("clerk-add-subscriber-btn");
      var clerk_input = document.getElementById("clerk-add-subscriber-input");
      var clerk_message = document.getElementById("clerk-subscribe-message");
      Clerk("call", "subscriber/subscribe", {
         email: clerk_input.value
      },
      function(response) {
         clerk_message.style.color = "#008001";
         clerk_message.innerText = "You are now subscribed!";
         clerk_btn.innerText = "Subscribed!";
         clerk_btn.style.opacity = "0.5";
         clerk_btn.disabled = true;
      },
      function(response) {
         clerk_message.style.color = "#EE360E";
         clerk_message.innerText = "Could not subscribe. Please try again.";
      });
   }
</script>

<style>
   .clerk-sign-up {
      width: 50%;
      padding: 60px 0;
      max-width: 800px;
      min-width: 500px;
      margin: 40px auto;
      background-color: #FEFAF4;
   }
   .clerk-sign-up-headline {
      margin: 0 14px 14px;
      text-align: center;
   }
   .clerk-sign-up-subtitle {
      margin: 14px 14px 28px;
      text-align: center;
      color: #808080;
   }
   .clerk-input-wrapper {
      margin: 10px auto;
      text-align: center;
   }
   #clerk-add-subscriber-input {
      height: 28px;
      width: 50%;
      padding: 0 0 0 6px;
      border: 1px solid #D3D3D3;
   }
   #clerk-add-subscriber-btn {
      height: 30px;
      background-color: #008001;
      border: 1px solid #008001;
      color: white;
      cursor: pointer;
   }
   #clerk-subscribe-message {
      height: 20px;
      margin: auto;
      text-align: center;
   }
</style>

To subscribe to a specific list, add list_id. List IDs are found in Email > Subscribers > Lists.

Clerk("call", "subscriber/subscribe", {
  email: "customer@example.com",
  list_id: "FSY27248"
});

Using the API #

Use the API when your sign-up form or backend should manage subscribers directly.

Call subscriber/subscribe to add an email address as a subscriber:

curl -X POST https://api.clerk.io/v2/subscriber/subscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com"
  }'

To subscribe to a specific list, include list_id:

curl -X POST https://api.clerk.io/v2/subscriber/subscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com",
    "list_id": "FSY27248"
  }'

Read the full reference at docs.clerk.io/reference/subscriberssubscribe.

Unsubscribing #

Unsubscribing is how recipients opt out of marketing emails.

Every marketing email must include a way for recipients to unsubscribe. How you manage it depends on whether the recipient clicks a link in an email or whether your backend handles the opt-out.

Using an external platform — Keep using your existing platform’s unsubscribe link. Klaviyo, Mailchimp, or your other platform handles the opt-out and keeps the subscriber list in sync.

Sending through Clerk.io — Add Clerk.io’s unsubscribe link to the design. If you use Ask Clerk.io, ask it to include an unsubscribe link and it will add one for you.

Using unsubscribe links #

For designs you build manually, use the link below.

The {{ email }} variable is replaced with each recipient’s address at send time. Replace YOUR_PUBLIC_API_KEY with the Public Key from Developers > API Keys.

<a href="https://api.clerk.io/v2/subscriber/unsubscribe?key=YOUR_PUBLIC_API_KEY&email={{ email }}&redirect=true">Unsubscribe</a>

To unsubscribe from a specific list only, add list_id:

<a href="https://api.clerk.io/v2/subscriber/unsubscribe?key=YOUR_PUBLIC_API_KEY&email={{ email }}&list_id=FSY27248&redirect=true">Unsubscribe from this list</a>

To redirect to your own confirmation page after unsubscribing, add redirect_url:

<a href="https://api.clerk.io/v2/subscriber/unsubscribe?key=YOUR_PUBLIC_API_KEY&email={{ email }}&redirect=true&redirect_url=https://yoursite.com/unsubscribed">Unsubscribe</a>

Using the API #

Use subscriber/unsubscribe to unsubscribe an email address programmatically.

This is useful for custom unsubscribe pages or backend workflows.

curl -X POST https://api.clerk.io/v2/subscriber/unsubscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com"
  }'

This unsubscribes globally. To unsubscribe from a specific list only, include list_id:

curl -X POST https://api.clerk.io/v2/subscriber/unsubscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com",
    "list_id": "FSY27248"
  }'

Read the full reference at docs.clerk.io/reference/subscribersunsubscribe.

Store Personalization #

Store personalization controls the default brand assets Clerk.io uses in email designs.

Go to Email > Configuration > Personalization to set your store logo. You can upload an image manually or use Auto-detect from website to let Clerk.io find it on your storefront.

The logo set here is used as the default logo in Clerk.io-built email designs. If you build designs manually, you can still reference the logo URL directly in the template markup.

Email Designs #

Ask Clerk.io Design Studio showing an email design preview with product recommendations

An email design is the visual template Clerk.io uses to build the email it sends.

Every campaign and automated flow needs a design. The design controls layout, colours, text, product blocks, unsubscribe links, and anything else the recipient sees.

With Ask Clerk.io Design Studio #

The easiest way to create a design is with Ask Clerk.io Design Studio.

Describe what you want in plain language, such as layout, colours, which products to show, and how sale prices should look. Design Studio builds a preview inline in the chat for you to review and refine.

You can also point it at your site or attach a screenshot. It will use that as a visual reference, which is considerably faster than explaining your shade of green like it is a suspect in a police lineup.

With MJML #

Use the built-in MJML editor when you want more control over the markup.

MJML compiles to HTML that renders consistently across Gmail, Outlook, Apple Mail, and other email clients. See the MJML Designs guide for a full walkthrough and examples.

All email designs in Clerk.io are responsive. They adapt automatically to desktop, tablet, and mobile.

Static Images #

Use the Media Library for static images like banners, logos, and seasonal headers.

Images uploaded there get a template reference like {{ media.your-image }} that you can use in any design.

You can also attach an image directly in Ask Clerk.io and ask it to upload the image and use it in the design.

Email Identification #

Email identification links a visitor session to an email address.

It is required for automated flows like browse abandonment, welcome series, and Abandoned Cart. Without it, Clerk.io may know what a visitor did, but not who to email about it.

Every visitor on your site gets a visitor ID. At first, that visitor ID is anonymous. Email identification connects it to an email address when the visitor types their email or returns while logged in.

Using Clerk.js #

Use collect_email to let Clerk.js detect email fields automatically.

If you use one of Clerk.io’s installable plugins, activate collect_email directly from the plugin settings. This applies to DanDomain Classic, Magento 1, Magento 2, PrestaShop, Shopware 6, VTEX, and WooCommerce.

For other setups, enable it in your Clerk.js config:

Clerk('config', {
  key: 'your-public-api-key',
  collect_email: true
});

Clerk.js will monitor email input fields and log the address when a visitor types one in.

This works for checkout fields, newsletter sign-ups, login forms, and other <input type="email"> elements.

If a customer is already logged in, log their email once per session with Clerk('call', 'log/email').

if (!sessionStorage.getItem('clerk_email_logged')) {
  Clerk('call', 'log/email', {
    email: 'CUSTOMER_EMAIL'
  });
  sessionStorage.setItem('clerk_email_logged', '1');
}

Replace CUSTOMER_EMAIL with the real email address from your platform. Only render the script when an email address is available.

Using the API #

Use log/email to associate a visitor ID with an email address.

Call it once per session when an email address is available. This applies when a customer logs in and when they return already logged in.

curl -X POST https://api.clerk.io/v2/log/email \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "email": "customer@example.com",
    "visitor": "SESSION_VISITOR_ID"
  }'

Replace SESSION_VISITOR_ID with the visitor ID for the current session.

When using the API, you are responsible for generating and maintaining the visitor ID. See the Tracking guide for details.

Cart Tracking #

Cart tracking tells Clerk.io what a visitor currently has in their cart.

It is required for Abandoned Cart emails. When a visitor leaves without buying, Clerk.io can only send the cart contents if the cart has been tracked.

Call cart tracking whenever the cart changes. This includes when a product is added, removed, or when the cart is fully updated.

With Clerk.js #

If you use the Magento 1, Magento 2, PrestaShop, or WooCommerce plugin, cart tracking is handled automatically.

For other setups, notify Clerk.io of the current cart contents using the set method. Each call is tied to the current visitor session.

Clerk('cart', 'set', [1234, 5678, 42]);

Read more in the Shopping Cart integration.

With the API #

Use log/cart/update to set the cart to its current state.

Call it whenever the cart changes, passing the full list of products currently in the cart.

curl -X POST https://api.clerk.io/v2/log/cart/update \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "your-public-api-key",
    "visitor": "SESSION_VISITOR_ID",
    "products": [
      {"id": 1234, "quantity": 2},
      {"id": 5678, "quantity": 1}
    ]
  }'

You can also pass email instead of, or in addition to, visitor if the email address is already known.