Batch update email information via API



I currently have a list of email contacts in a separate database that I would like to sync to HubSpot via the API. My separate database is the source of truth. However, it does not appear this can be done via the Contacts endpoint, as attempting to update the Opt-out property returns the following error:

hs_email_optout_5482620 is a read only property; its value cannot be set

I have read several posts that indicate this needs to be done via the Email API, and I found the endpoint that controls this here:

PUT /email/public/v1/subscriptions/:email_address

However it looks like this can only be done one address at a time. My questions are:

  1. Is there a batch endpoint that can set the status for multiple emails at once?
  2. Can the opt-out status be set to either subscribed or unsubscribed via the API? I've read conflicting information on this; some posts seem to indicate that once someone is unsubscribed it is physically impossible to subscribe them again, while other posts (including the endpoint documentation) seems to indicate that the subscription status can be set either way.

One other note, my intent is to set this universally for each email contact, not for individual mail types.

Thank you in advance.


Welcome, @abbeyroad1971.

Happy to clarify:

  1. No; at this time, there is no batch endpoint. We usually recommend looping through this endpoint.
  2. Yes and no. An email address with either an OPT_IN or NOT_OPTED status (see this related topic) for a given subscription type can be switched to OPT_OUT, but an email address that already has an OPT_OUT status for a given subscription type cannot be switched to OPT_IN without action from the contact (see this related topic). Similarly, an email which has unsubscribed from all email communication cannot be opted into anything via the Email API.

Per your last comment, opting in must be done for each subscription type. You can do all in one call for a given email address, but you cannot send something like:

  "subscribeToAll": true

and expect it to automatically switch each subscription type to OPT_IN.