This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Newsletter Brevo Module

Configuration

Brevo_account

  • Create an account on the Brevo website and create an API key for it. At time of writing, this can be done at https://app.brevo.com/settings/keys/api

  • Then, create a Brevo_account entity and use the brevo-credentials action to connect it via the API key from the Brevo account.

  • Finally, copy the auto-generated webhook url and create a webhook in your Brevo account. At time of writing, this can be done at https://my.brevo.com/advanced/webhook

Brevo_folder

Can be used to group lists together.

User_newsletter_category

This is the equivalent to lists in Brevo.

Brevo_attribute

Allows sending more data per contact to Brevo. Paths are validated, so configuring something very wrong is hard, just make sure the datatypes match. Categories can usually be matched to the unique ids of lookup entities.

Synchronisation

BrevoSynchronisationBatchJob synchronises users with related User_newsletter_category every few minutes. Changes in lists and email addresses in Brevo get synced via BrevoWebhook. Additionally, changes to email addresses, Brevo_attribute or removals specifically of User_newsletter_category from users get synchronised to via listeners to Brevo.

Local Development / Test Systems

By default, brevo synchronisation is disabled in test or development environments. Setting the property nice2.brevo.disableTestSync to false enables synchronisation in these environments. This may be used to test the integration with brevo in the test environment, but should not be enabled for longer time periods as it may lead to conflicts with the production environment.

Testing

Webhook

Testing the Brevo Webhook can be hard, because blindly deploying changes to a test system is inefficient, while the local development environment is not easily made available on the internet. The best way we’ve found so far, is to intercept the webhook requests, and then send them to your local development environment by hand. To do this:

  1. Add a webhook in Brevo pointing to a site intercepts requests (like https://webhook.site)

    • Brevo UI changes all the time, so trying to document it here in detail is pointless

    • At time of writing, we handle the events contact_updated, unsubscribe, and contact_deleted

  2. Perform whatever changes you wish to test in Brevo

  3. Look at your webhook intercept and copy the relevant JSON body

  4. Send the copied JSON body to http://localhost:8080/nice2/rest/newsletterbrevo/brevo-webhook/{accountUuid} with your prefered REST client

    • Open up the detail page of your Brevo_account in Nice if you do not know your accounts uuid

Special mention should go to the unsubscribe event. This is only triggered when a user unsubscribes via the link sent to them in a Brevo mail, not when unsubscribing someone in the admin interface by hand. To test this:

  1. Login with the admin account owner of the Brevo account you are testing

    • Check Bitwarden for our own test account

  2. Create a new contact with a valid email address you can access

  3. Send an email from Brevo to this new contact

    • Again, since Brevo changes all the time, this might be different for you, but at time of writing this involves creating a new campaign in the Marketing -> Campaigns, configuring a sender email (already setup in out test account), recipients, and the template (use whatever is easiest)

    • Do not use the test email function, this will not work

    • Open the sent email on the receiving end, and unsubscribe via the link