Sync MailForge unsubscribes and bounces to HubSpot nightly

PromptCreate

Build me a scheduled code workflow that syncs my MailForge suppression list into HubSpot every night so anyone who unsubscribed or bounced in MailForge is also flagged as email opted-out in the CRM. This is a deterministic pipeline with no reasoning steps — fetch, iterate, look up, update — so please build it as a code workflow.

Trigger: cron, daily at 02:00 in the workspace timezone.

Steps:

1) Call the MailForge List Suppressions operation and page through every suppressed email address. Use per_page=100 and keep advancing page until the response indicates there are no more pages. Collect the full list of suppressed emails (with their reason and suppressed-at timestamp if available).

2) For each suppressed email, call the HubSpot Search Contacts operation filtered by that email address to find the matching CRM record. If no contact is returned, skip silently and continue. If a contact is returned, read its current email opt-out property.

3) If the contact's opt-out flag is already true, short-circuit and move on (do not call Update Contact). If it is not already set, call the HubSpot Update Contact operation for that contact id and set the email opt-out property (default to hs_email_optout, but let me pick a different property name at setup time) to true. Also stamp a last-synced timestamp property (default name mailforge_suppression_last_synced_at) with the current ISO-8601 datetime.

4) At the end of the run, log a compact summary: total suppressions fetched, contacts matched in HubSpot, contacts newly opted out, contacts already opted out and skipped, and emails with no HubSpot match.

Requirements: the run must be idempotent (rerunning the same day should be a no-op after the first successful pass). Respect HubSpot's Search API rate limit of 4 requests per second; add gentle spacing between search calls. On HTTP 429 from HubSpot, honor the Retry-After header. Do not create new HubSpot contacts under any circumstances — this workflow only updates records that already exist.

Connections I will provide: MailForge (API key + instance URL) and HubSpot (OAuth with crm.objects.contacts.read and crm.objects.contacts.write).

What does this prompt do?

Runs quietly every night at 2am and pulls every suppressed email address out of MailForge (unsubscribes, bounces, complaints, and manual adds).
Looks up each of those addresses in HubSpot and, when it finds a matching contact, marks them as opted out of email so your sales sequences skip them.
Stamps a last synced date on every updated contact so you can see exactly which records the sync has touched.
Skips addresses that have no HubSpot record and contacts that are already opted out, so reruns stay clean and quota friendly.

What do I need to use this?

A MailForge account you can log in to (you will paste a key from Settings and your instance web address).
A HubSpot account with permission to view and update contact records.
About five minutes to connect both accounts the first time you run the workflow.

How can I customize it?

Change when it runs. Move the schedule earlier, later, or to a weekly cadence if daily is more than you need.
Choose which HubSpot field gets set. The default is the standard email opt-out field, but you can point it at a custom checkbox or a status field your team already uses.
Narrow the scope. If you only want to sync hard bounces and unsubscribes (and ignore soft bounces), filter the MailForge list before it reaches HubSpot.

FAQs

Will this delete or archive HubSpot contacts?

No. It only updates the email opt-out field on contacts that already exist in HubSpot. Nothing is created, deleted, or archived.

What happens to email addresses that are not in HubSpot?

They are skipped silently. The workflow only touches HubSpot contacts that already exist, so unknown addresses are simply ignored on that run.

Does it re-update contacts that are already opted out?

No. The workflow checks each contact first and skips ones that are already marked opted out. That keeps runs fast and avoids burning through your HubSpot API allowance.

How long will the nightly run take?

It depends on the size of your MailForge suppression list. For most teams with a few thousand suppressed addresses, a full run finishes in a handful of minutes.

Can I run this against a sandbox HubSpot first?

Yes. Connect the sandbox HubSpot account when you set up the workflow, verify a few contacts get flagged correctly, then swap in your production HubSpot connection.