Skip to main content

Email Preferences

Workflows send two kinds of email: transactional email, which always goes out, and marketing email, which members can opt out of entirely or one topic at a time. The allegro.email methods let a signed-in member see and change those choices on your own site, for example on an account or newsletter preferences page.

Operators create topics in the Allegro admin under Workflows → Topics. Each topic has a slug, and the SDK refers to topics by slug. See Workflow Emails.

Requires a signed-in member

These methods act on the currently authenticated member. Called without a signed-in member, they reject with an AllegroApiError whose statusCode is 401.

Reading preferences​

allegro.email.preferences() resolves with the member's marketing state and every topic:

window.allegro.push(async function (allegro) {
    const { marketing, topics } = await allegro.email.preferences();

    topics.forEach(function (topic) {
        console.log(topic.slug, topic.name, topic.subscribed);
    });
});
type EmailPreferences = {
    marketing: boolean;
    topics: { slug: string; name: string; subscribed: boolean }[];
};
FieldDescription
marketingfalse when the member has opted out of all marketing email.
topicsEvery topic the organization has defined, sorted by name.
topics[].slugThe topic's slug. Pass it to optOut() and optIn().
topics[].nameThe topic's display name.
topics[].subscribedfalse when the member opted out of this topic, or of all marketing email.

Opting out​

allegro.email.optOut(topic?: string): Promise<EmailPreferences> opts the member out of one topic by slug, or of all marketing email when you pass no topic. It resolves with the updated preferences:

window.allegro.push(async function (allegro) {
    // One topic
    await allegro.email.optOut('weekly-news');

    // All marketing email
    const preferences = await allegro.email.optOut();
});

Opting out is recorded with the source SDK on the member's Email tab in the admin. Transactional email is unaffected.

Opting back in​

allegro.email.optIn(topic?: string): Promise<EmailPreferences> reverses an opt-out and resolves with the updated preferences:

window.allegro.push(async function (allegro) {
    await allegro.email.optIn('weekly-news');
});

The two kinds of opt-out are independent:

  • optIn() with no topic removes the all-marketing opt-out and leaves topic opt-outs in place. A member who had also opted out of weekly-news stays opted out of it.
  • optIn('weekly-news') removes only that topic's opt-out. While the member is still opted out of all marketing email, subscribed stays false for every topic.

Errors​

statusCodeWhen
401No member is signed in.
422The topic slug doesn't match any topic.
try {
    await allegro.email.optOut(slug);
} catch (error) {
    if (error.statusCode === 401) {
        // Ask the visitor to sign in first
    }
}

Example: a preferences form​

<form id="email-preferences">
    <label>
        <input type="checkbox" name="marketing" />
        Send me marketing email
    </label>
    <fieldset id="topics">
        <legend>Topics</legend>
    </fieldset>
</form>

<script>
    window.allegro.push(async function (allegro) {
        const form = document.getElementById('email-preferences');
        const topicList = document.getElementById('topics');

        function render(preferences) {
            form.elements.marketing.checked = preferences.marketing;
            topicList
                .querySelectorAll('label')
                .forEach((label) => label.remove());

            preferences.topics.forEach(function (topic) {
                const label = document.createElement('label');
                const input = document.createElement('input');
                input.type = 'checkbox';
                input.name = topic.slug;
                input.checked = topic.subscribed;
                input.disabled = !preferences.marketing;
                label.append(input, ' ' + topic.name);
                topicList.append(label);
            });
        }

        form.addEventListener('change', async function (event) {
            const { name, checked } = event.target;
            const topic = name === 'marketing' ? undefined : name;

            render(
                checked
                    ? await allegro.email.optIn(topic)
                    : await allegro.email.optOut(topic),
            );
        });

        render(await allegro.email.preferences());
    });
</script>