Daily HubSpot to SendGrid subscriber sync

Build a code workflow that keeps a SendGrid marketing list in sync with newly subscribed HubSpot contacts. The pipeline is fully deterministic — search, map, batch upsert — so no AI in the loop.

Trigger: cron, daily at 1:00 AM in the workspace's timezone.

Step 1 — Pull new subscribers from HubSpot. Use HubSpot's Search Contacts operation. Filter on (a) lifecyclestage IN ['subscriber', 'lead'] AND (b) hs_lastmodifieddate >= now() - 24h. If the connected workspace has a boolean custom property named 'subscribed_to_newsletter' (or similar), expose it as an optional filter the user can enable at setup so they can narrow the audience further. Request the properties: email, firstname, lastname, lifecyclestage, hs_lastmodifieddate, plus any extra HubSpot properties the user maps to SendGrid custom fields. Page through all results using HubSpot's cursor pagination (paging.next.after) until exhausted. Search is capped at 10,000 results per run, which is well above the daily new-subscriber volume for normal workspaces.

Step 2 — Map each HubSpot contact to SendGrid's schema. Lowercase the email (SendGrid stores emails lowercased and SGQL is case-sensitive). Set first_name and last_name. For each user-configured field mapping (HubSpot property → SendGrid custom field id), copy the value over, skipping nulls.

Step 3 — Upsert into SendGrid. Call SendGrid's Create or Update Contacts operation (PUT /marketing/contacts). Pass list_ids = [the configured list id] so the contacts are added to the target marketing list as part of the upsert. SendGrid accepts up to 30,000 contacts or 6 MB per call, so chunk by 30,000 if needed but a single batch is almost always enough. The endpoint returns 202 Accepted with a job_id — treat this as fire-and-forget; the import completes in the background within minutes.

Step 4 — Write to the run log: the number of contacts pulled from HubSpot, the number sent to SendGrid, the SendGrid job_id, and the target list_id. If HubSpot returned zero matching contacts, log 'no new subscribers' and exit cleanly (do not call SendGrid).

Configuration the user should provide at setup: SendGrid list_id (target marketing list); optional toggle for the 'subscribed to newsletter' filter and the custom property name to use; a list of HubSpot-property → SendGrid-custom-field mappings (defaults: firstname → first_name, lastname → last_name); optional override for the lookback window (default 24 hours) and the cron time (default 1:00 AM).

Error handling: on HubSpot 429, respect Retry-After. On SendGrid 429, back off until X-RateLimit-Reset. On SendGrid validation errors in the upsert response, surface the offending email(s) in the run log so the user can fix the source record in HubSpot.