Does it support subscription preferences API?

[hubspot]

Does it support subscription preferences API?

[ksvirkou-hubspot]

Hi @alex-mironov
It hasn't supported yet.

[rnwolfe]

@alex-mironov I was looking into this API endpoint support, as well, but you can use the manual call functions to handle the endpoints for now. Here's what I did in my Node.js app as an example:

/**
 * Attempt to opt-in a HubSpot Contact to marketing emails. This should **only** be done with user consent.
 * 
 * @param {email} email The email to attempt to opt in to marketing subscription.
 * @returns {Promise} The HubSpot API response object if successful, otherwise logs an error to system.
 */
exports.optInToMarketingEmails = async email => {
  // Have to do a manual API call because subscription preferences are not yet wrapped in the SDK
  // @see: https://github.com/HubSpot/hubspot-api-nodejs/issues/71
  return hubspotClient
    .apiRequest({
      method: 'POST',
      path: '/communication-preferences/v3/subscribe',
      body: {
        emailAddress: email,
        subscriptionId: await this.getMarketingSubscriptionId(),
        legalBasis: 'LEGITIMATE_INTEREST_PQL',
        legalBasisExplanation:
          email +
          ' expressed interest in further emails when requesting resources at an event.'
      }
    })
    .then(response => {
      logging.systemInfo(`${email} gave promotional consent and was opted into HubSpot Marketing emails.`)
      return response.body;
    })
    .catch(e => {
      const body = e.response.body;
      if (body.message.includes('they have unsubscribed') || body.message.includes('already subscribed')
      ) {
        // Log as informational if contact has previously unsubscribed or is already subscribed.
        logging.systemInfo(`${e.response.body.category}: ${e.response.body.message}`, LOG_TYPE);
      } else {
        logging.systemError(`${e.response.body.category}: ${e.response.body.message}`, LOG_TYPE);
      }
    });
};

/**
 * Gets all existing subscription definitions in the HubSpot instance.
 * 
 * @returns {Promise} All existing subscription definitions in the HubSpot instance.
 */
exports.getSubscriptionDefinitions = async () => {
  return hubspotClient
    .apiRequest({
      method: 'GET',
      path: '/communication-preferences/v3/definitions'
    })
    .then(response => response.body);
};

/**
 * Get the subscription statuses for any of the Contact's subscriptions.
 * 
 * @param {email} email The HubSpot Contact's email 
 * @returns {Promise} A HubSpot API response object with the Contact's communciation preferences.
 */
exports.getUserCommunicationPreferences = async email => {
  return hubspotClient
    .apiRequest({
      method: 'GET',
      path: '/communication-preferences/v3/status/email/' + email
    })
    .then(response => response.body);
};

/**
 * Get the subscription ID for the *first* Marketing subscription returned.
 * 
 * @returns {Promise<string>} The first Marketing subscription's ID.
 */
exports.getMarketingSubscriptionId = async () => {
  const definitions = await this.getSubscriptionDefinitions();
  // This can likely be handled better if multiple subscriptions exist
  return definitions.subscriptionDefinitions.find(sub => sub.purpose === 'Marketing').id;
};

The function names could probably be improved, but the usage of communication preferences, subscriptions, and other terminology is a bit intermixed in the documentation.

Also, I'm sure the use of .then().catch() as well as async/await is triggering to many, but I just don't like the try/catch paradigm.. 😄

Hope this helps someone.

[ksvirkou-hubspot]

HI @alex-mironov
The API was add in version 4.1.0

hubspotClient.communicationPreferences