The Email Subscriptions API is a service that allows your app to create, view, and update email subscriptions for a site's contacts. Any changes made with the Email Subscriptions API are reflected in the site's Contact List.

Wix keeps track of contacts' subscription and deliverability statuses. These statuses are automatically updated by Wix, although site contributors can change subscription status in the site Dashboard.

By using the Email Subscriptions API, your app can keep subscription and deliverability statuses in sync with an external email marketing tool.

The Email Subscriptions API allows your app to:

• Query existing email subscriptions
• Update or create subscriptions by email address
• Generate unsubscribe links for individual recipients
• Listen for changes to subscription or deliverability statuses for site contacts (coming soon)

• The email subscription object contains an email, subscription status, and deliverability status.
• Subscription status indicates a contact's opt-in or opt-out status for marketing emails.
• Deliverability status indicates if the emails were opened or bounced, if the contact marked an email as spam, or if no activity has been reported to Wix.

This article shares possible use cases your app could support, as well as an example flow that could support each use case. You're certainly not limited to what's on this page, but it can be a helpful jumping off point as you plan your app.

Some site owners communicate with their subscribers through an external email marketing tool, even if they manage their subscribers in Wix. To comply with privacy regulations, site owners need to ensure that only contacts who have opted in to marketing emails will receive those emails.

Email subscription status is conveyed in the subscriptionStatus field. To allow site owners to email only opted-in contacts, your app could request subscription statuses from Wix before starting a campaign with this basic flow:

1. Request the campaign recipients from the external tool. Craft your code so the emails are formatted as an array.

2. Request the list of subscription statuses from Wix by including the array of emails in Query Email Subscriptions:

   Copy Code
   {
     "filter": {
       "email": {
         "$in": [
           "recipient-1@first.com",
           "recipient-2@second.com",
           "...the-rest-of-your-email@list.com"
         ]
       }
     }
   }

3. Craft your code to further filter for the contacts whose subscriptionStatus is SUBSCRIBED, then extract those email addresses into an array.

4. Return the final, filtered array to the external email marketing tool. This is the confirmed list of contacts who have opted-in to marketing emails from the site owner, and who can now receive the email campaign.

Site owners can keep their email marketing tool updated with their Wix Contact List with a two-way sync. To synchronize Wix and an external system, think about how your app will handle these flows:

• Initial setup
• Synchronizing from Wix to the email marketing tool
• Synchronizing from the email marketing tool to Wix

1. Create a mapping from the Wix fields to the email marketing tool fields, to be used whenever Wix and the email marketing tool are synchronized. Store this mapping on your app's server.

2. You'll soon see that this flow relies on webhooks to trigger syncs between Wix and the email marketing tool. To keep your app from getting caught in an endless loop, include logic that ignores a webhook that's triggered as the result of a sync.

Listen for any changes to Wix email subscriptions with the Email Subscription Changed Webhook. When this webhook is triggered, your endpoint will receive the email subscription in the payload.

You can bring those changes to the email marketing tool with a flow like this one:

1. Extract the data field — which is stringified JSON — and convert it to true JSON. After JSONified, it takes this structure:

   Copy Code
   {
     "subscription": {
       "id": "9c130f52-31c4-11ed-a261-0242ac120002",
       "email": "changed-subscription@wix.com",
       "subscriptionStatus": "UNSUBSCRIBED",
       "deliverabilityStatus": "VALID",
       "createdDate" : "2019-10-30T17:22:10.299Z",
       "updatedDate" : "2019-11-13T20:14:49.458Z"
     }
   }

2. Use the mapping (from the initial setup) to copy the email and subscriptionStatus to the email marketing tool.

3. Ignore the resulting event from the email marketing tool so you don’t create an endless loop of updates.

Listen for changes to email subscriptions from the external CRM. When your app detects a change that it needs to synchronize, follow this basic flow:

1. Parse the payload to extract email and subscription status.

2. Use the mapping (from the initial setup) to copy the email and subscription status to Wix. You'll use Upsert Email Subscription to send the data:

   Copy Code
   {
     "subscription": {
       "email": "changed-subscription@email-marketing-tool.com",
       "subscriptionStatus": "SUBSCRIBED"
     }
   }

3. As before, ignore the resulting event from Wix so you don’t create an endless loop of updates.