There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Update email subscription status for an email address

Last updated May 15, 2023

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

Method Details

HTTP Methods:

PUT

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Required Scope:

content

Use this endpoint to update an email address' email type subscription status or permanently unsubscribe an email address from all email.

Use case for this endpoint: The endpoint is useful if a system collects opt-out information outside of HubSpot, but needs to prevent future mailings to those contacts inside of HubSpot.

Status updates and contact records

The subscription status is tied to the email address, and not a specific contact record. Because of this, it is possible to update the status for an email address even if there is not currently a contact with that email address. If the status is updated for an email address that isn't currently associated with a contact and a contact is later created, the status update will apply to the new contact. The same would be true if there was an existing contact was deleted and a new contact with the same email address was created.

Note: If you OPT OUT of all emails or a specific email subscription type for a recipient, there is NO UNDO for this operation.

Required parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Email address :email_address - Used in the request URL The email address for which you are updating subscription status.
JSON body See examples Describe whether you want to unsubscribe the email address from all emails or some subset of them. If you want to record the legal basis for GDPR, you can select from "LEGITIMATE_INTEREST_PQL", "LEGITIMATE_INTEREST_CLIENT", "PERFORMANCE_OF_CONTRACT", "CONSENT_WITH_NOTICE", or "NON_GDPR". The explanation is free-form text noting any specific consent information you wish to record.
optState Used in the JSON body Determines whether a contact is opted in or out of a given email subscription. The possible values are "OPT_IN", "OPT_OUT", and "NOT_OPTED"

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example PUT URL: https://api.hubapi.com/email/public/v1/subscriptions/example@domain.com Example PUT data for unsubscribing an email address from all email: { "unsubscribeFromAll": true } Example PUT data for subscribing specific email types: { "subscriptionStatuses": [ { "id": 7, "subscribed": true, "optState": "OPT_IN", "legalBasis": "PERFORMANCE_OF_CONTRACT", "legalBasisExplanation": "We need to send them these emails as part of our agreement with them." } ], "portalSubscriptionLegalBasis": "LEGITIMATE_INTEREST_CLIENT", "portalSubscriptionLegalBasisExplanation": "They told us at a conference that they're interested in receiving communications." } Example PUT data for unsubscribing from specific email types: { "subscriptionStatuses": [ { "id": 7, "subscribed": false, "optState": "OPT_OUT" } ] } On success, returns a 200 response with this JSON: { "status": "ok" }
Example curl: curl -XPUT -H 'Content-Type: application/json' -d '{"subscriptionStatuses": [{"id": 7, "subscribed": false}]}' "https://api.hubapi.com/email/public/v1/subscriptions/jerry@example.org?portalId=PORTAL_ID&hapikey=demo"