Loops opt-in/opt-out for public contact lists

[JoseSzycho]

We need to define and implement proper opt-in / opt-out handling for public contact lists when using the Loops Contact Provider.

[JoseSzycho]

@jacobsmith928 We’re still running into some limitations due to Loops’ lack of flexibility.

Loops automatically adds an Unsubscribe page at the bottom of all campaign emails, and there is currently no option to remove it.

This page is auto-generated based on the mailing list configuration (public or private).

Given this, Loops effectively becomes the source of truth for subscription preferences. Building a configuration page in the Cloud Portal for each user would require a significant amount of additional work. We wouldn’t be able to reuse our existing controller design patterns, and keeping both systems in sync would be particularly challenging due to Loops’ rate limit of 10 requests per second.

We currently have ~350 contacts. Each sync would require at least two API calls per contact (~700 calls total), making synchronization fragile and difficult to manage. While this could be addressed using custom API endpoints, it would introduce additional complexity and implementation effort.

Given these constraints, I’d like to propose that we continue using Loops’ built-in Unsubscribe functionality and avoid implementing a separate Cloud Portal configuration for this purpose.

We’ll wait for your feedback.

cc @drewr

[jacobsmith928]

Well, we are required by law to provide a method for unsubscribe actions. Since we don't yet have a way for users to do this, i think we have to use the included Loops example. I'm fine with that for now, but we need to discuss how to pull back the subscription of marketing lists into Milo, and we will definitely want to provide a way for users to subscribe or unsubscribe from the customer portal.

I think we should have a real time chat about this overall approach and ambition.

[JoseSzycho]

Sounds good, agreed.

I’ll formalize the loops-email-provider repo and start creating the service, including the Milo sync.

Right now loops sync is running in a patched version of email-provider-resend, with limited functionality, which I put together as a quick workaround a few weeks ago.

I’ll clean that up and move it into a proper, dedicated service, and after that will continue with the opt-in, opt-out work

[JoseSzycho]

Doing tests on Loops webhook system.

So far, I'm correctly receiving users opt-in/opt-out updated from the Loops per unsubscribe page.

Unsubscribed received event

{
  eventName: 'contact.mailingList.unsubscribed',
  eventTime: 1766083078,
  webhookSchemaVersion: '1.0.0',
  contactIdentity: {
    id: 'cmhxvsmag0jjb0i05a6myhmwc',
    email: 'joseszychowski@gmail.com',
    userId: '875be59f-b713-4825-bd35-bcd61f4061b3'
  },
  mailingList: {
    id: 'cmh1115fg060y0iys4s8l817s',
    name: 'Email Newsletter',
    description: 'Signups to receive the monthly Datum Newsletter',
    isPublic: true
  }
}

Subscribed received event

{
  eventName: 'contact.mailingList.unsubscribed',
  eventTime: 1766083062,
  webhookSchemaVersion: '1.0.0',
  contactIdentity: {
    id: 'cmhxvsmag0jjb0i05a6myhmwc',
    email: 'joseszychowski@gmail.com',
    userId: '875be59f-b713-4825-bd35-bcd61f4061b3'
  },
  mailingList: {
    id: 'cmh1115fg060y0iys4s8l817s',
    name: 'Email Newsletter',
    description: 'Signups to receive the monthly Datum Newsletter',
    isPublic: true
  }
}

Doing further tests on how webhooks behaves is the receiver server is offline

[JoseSzycho]

The webhooks have a retry mechanism with exponential retry time. We'll be safe to use that for syncing the ContactGroupMembershipsRemovals (used for the opt-in/opt-out).

That being said, I will stop working on this task for a few days, as I need first to create the proper implementation of the email-provider-loops service, and then deploy it to staging, and production.

Working branch: https://github.com/datum-cloud/email-provider-loops/tree/feat/initialize-project

Here's the working branch of the controllers, Loops SDK already created and working correctly:
https://github.com/datum-cloud/email-provider-loops/tree/feat/contact-controllers

Once controllers, and deploy are on place, I will create the webhook server, and continue with the implementation of the opt-in/opt-out functionality.

cc @drewr