How to register subscriptions with a self-managed form

Overview

Gaining new subscribers is critical to the ongoing success for any newsletter. This guide explains how to modify existing, self-managed forms to push new subscribers to Echobox.

Alternative methods for registering new subscribers are documented here:

Why would I use a self-managed form?

The hosted forms provided by Echobox are simple to use and offer various configuration options but are ultimately far less flexible in terms of styling and functionality compared to a custom coded sign-up form.

You can register any first-party data via self-managed forms providing the fields exist on the subscriber list in Echobox and the data submitted is type safe

How to use a self-managed form

The HTML example below illustrates how you can modify your existing form, or you can use this example and style it how you wish.

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Subscribe Form</title>
</head>

<body>
    <form action="https://subscribe.campaign-list.com/v1/public/campaigns/subscribe" method="POST">
        <h2>Subscribe to our mailing list!</h2>
        <div>
            <label for="first-name">First Name:</label>
            <input type="text" name="first-name" id="first-name" placeholder="Your First Name" required>
        </div>
        <br>
        <div>
            <label for="last-name">Last Name:</label>
            <input type="text" name="last-name" id="last-name" placeholder="Your Last Name" required>
        </div>
        <br>
        <div>
            <label for="email">Email:</label>
            <input type="email" name="email" id="email" placeholder="email@address.com" required>
        </div>
        <br>
        <input type="submit" value="Subscribe" />
        <input type="hidden" name="campaignURN" value="urn:newsletter:campaign:XXXXX" />
    </form>
</body>

</html>

The campaignURN is important as it specifies to Echobox which campaign the new subscriber should be added to.

Additionally,

Endpoint: POST https://subscribe.campaign-list.com/v1/public/campaigns/subscribe — this is the endpoint URL call that is public and unauthenticated. The form is just a thin client for it.
Required fields: The email field is only field that is mandatory to register a subscription. However, in this example first-name, last-nameare marked as required via client-side validation.

Where do I find my campaignURN?

The campaignURN in the example above will need to be updated to your campaignURN which you can copy from your browser URL when you are viewing the campaign in the Echobox Email platform.

How do I support multiple campaigns?

The public API in the example above has no native multi-campaign support so the recommendation is to loop over the subscriptions or alternatively use the authenticated endpoints as specified in Operating on subscriber data.

See below for an example of how to support multiple campaign subscriptions via a self-managed form:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Multi-Campaign Subscribe Example</title>
</head>
<body>
    <form id="signupForm">
        <div>
            <label for="email">Email:</label>
            <input type="email" name="email" id="email" required>
        </div>

        <div>
            <label>
                <input type="checkbox" name="campaignURN" value="urn:newsletter:campaign:AAAA">
                Dummy Campaign A
            </label>
        </div>
        <div>
            <label>
                <input type="checkbox" name="campaignURN" value="urn:newsletter:campaign:BBBB">
                Dummy Campaign B
            </label>
        </div>

        <button type="submit">Subscribe</button>
    </form>

    <script>
        document.getElementById('signupForm').addEventListener('submit', function (event) {
            event.preventDefault();

            const email = document.getElementById('email').value;

            const selectedCampaigns = Array.from(
                document.querySelectorAll('input[name="campaignURN"]:checked')
            ).map(input => input.value);

            if (selectedCampaigns.length === 0) {
                alert('Please select at least one campaign.');
                return;
            }

            // Fire one request per selected campaign, sequentially
            selectedCampaigns.reduce((promise, campaignURN) => {
                return promise.then(() =>
                    fetch('https://subscribe.campaign-list.com/v1/public/campaigns/subscribe', {
                        method: 'POST',
                        headers: { 'Content-Type': 'application/json' },
                        body: JSON.stringify({ email, campaignURN })
                    }).then(response => {
                        if (!response.ok) throw new Error(`Failed for ${campaignURN}`);
                    })
                );
            }, Promise.resolve())
            .then(() => alert('Subscribed to selected campaigns!'))
            .catch(error => alert(error.message));
        });
    </script>
</body>
</html>