About Email Subscriptions

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)

Terminology

  • 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.
Was this helpful?
Yes
No

Example Flows

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.

Check Wix for Subscription Status Before a Campaign

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
    1
    {
    2
    "filter": {
    3
    "email": {
    4
    "$in": [
    5
    "recipient-1@first.com",
    6
    "recipient-2@second.com",
    7
    "...the-rest-of-your-email@list.com"
    8
    ]
    9
    }
    10
    }
    11
    }
  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.

Sync Subscription Status with an Email Marketing Tool

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:

Part 1: Initial Setup

  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.

Part 2: Synchronizing to the External Tool

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
    1
    {
    2
    "subscription": {
    3
    "id": "9c130f52-31c4-11ed-a261-0242ac120002",
    4
    "email": "changed-subscription@wix.com",
    5
    "subscriptionStatus": "UNSUBSCRIBED",
    6
    "deliverabilityStatus": "VALID",
    7
    "createdDate" : "2019-10-30T17:22:10.299Z",
    8
    "updatedDate" : "2019-11-13T20:14:49.458Z"
    9
    }
    10
    }
  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.

Part 3: Synchronizing to Wix

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
    1
    {
    2
    "subscription": {
    3
    "email": "changed-subscription@email-marketing-tool.com",
    4
    "subscriptionStatus": "SUBSCRIBED"
    5
    }
    6
    }
  3. As before, ignore the resulting event from Wix so you don’t create an endless loop of updates.

Was this helpful?
Yes
No

Emailsubscription Object

Attributes
idstringRead-onlyformat GUID
Email subscription ID.

emailstringformat EMAIL
Email address.

subscriptionStatusstring
5 supported values:
UNKNOWNNOT_SETPENDINGSUBSCRIBEDUNSUBSCRIBED
Indicates the recipient's opt-in or opt-out status for marketing emails.
  • NOT_SET: No status specified. This is the default, initial value before any info about the email address is known.
  • PENDING: Subscription confirmation was requested, but recipient hasn't confirmed yet.
  • SUBSCRIBED: Recipient has opted in to marketing emails.
  • UNSUBSCRIBED: Recipient has opted out of marketing emails.
Defaults to NOT_SET.

deliverabilityStatusstring
5 supported values:
NOT_SETVALIDBOUNCEDSPAM_COMPLAINTINACTIVE
Indicates last reported status of sent emails.
  • NOT_SET: No status specified. This is the default, initial value before any info about the email address is known.
  • VALID: Emails to this email address are being delivered successfully.
  • BOUNCED: The last email to the recipient bounced or was rejected.
  • SPAM_COMPLAINT: The recipient registered a spam complaint with their email provider.
  • INACTIVE: Multiple campaigns have been delivered to this address without any engagement from the recipient. (No emails were opened and no content was clicked.) This status might impact subsequent emails sent to this address.
Defaults to NOT_SET.

createdDatestringRead-onlyformat date-time
Date and time the email subscription was created.

updatedDatestringRead-onlyformat date-time
Date and time the email subscription was last updated.
Was this helpful?
Yes
No

PostQuery Email Subscriptions

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves email subscriptions, given the provided paging, filtering, and sorting.

Currently, querying is supported on the email field with the $in array filter. For example, to query for emails "me@my.com" and "you@your.org", the filter should be formed like this:

Copy
1
{ "filter": {
2
"email": {
3
"$in": ["me@my.com", "you@your.org"]
4
}
5
}
6
}

To learn how to query email subscriptions, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Email Subscriptions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/email-marketing/v1/email-subscriptions/query

Was this helpful?
Yes
No

PostUpsert Email Subscription

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates or creates an email subscription for the requested email.

An email subscription is always returned in the response, regardless of whether it was updated or created.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Email Subscriptions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/email-marketing/v1/email-subscriptions

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostBulk Upsert Email Subscription

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates or creates multiple email subscriptions.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Email Subscriptions
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/email-marketing/v1/email-subscriptions/bulk

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No


Emailsubscription Email Subscription Changed

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Email Subscriptions
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
subscriptionobject
subscription
Was this helpful?
Yes
No