> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # QueryEmailSubscriptions # Package: communication # Namespace: EmailSubscriptionsService # Method link: https://dev.wix.com/docs/api-reference/crm/communication/email-subscriptions/query-email-subscriptions.md ## Permission Scopes: Manage Email Subscriptions: SCOPE.DC-MANAGE.EMAIL-SUBSCRIPTIONS ## Introduction 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: ```json { "filter": { "email": { "$in": ["me@my.com", "you@your.org"] } } } ``` To learn how to query email subscriptions, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). --- ## REST API ### Schema ``` Method: queryEmailSubscriptions Description: 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: ```json { "filter": { "email": { "$in": ["me@my.com", "you@your.org"] } } } ``` To learn how to query email subscriptions, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). URL: https://www.wixapis.com/email-marketing/v1/email-subscriptions/query Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: filter Method parameters: param name: filter | type: filter | description: Filter options. Currently, querying is supported on the `email` field with the `$in` array filter. | required: true param name: paging | type: Paging - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. Return type: QueryEmailSubscriptionsResponse - name: subscriptions | type: array | description: List of subscribed emails that matched the query options. - name: id | type: string | description: Email subscription GUID. - name: email | type: string | description: Email address. - name: subscriptionStatus | type: Status | description: Indicates the recipient's opt-in or opt-out status for marketing emails. Default: `NOT_SET`. - enum: - UNKNOWN: Undefined status. - 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. - name: deliverabilityStatus | type: Status | description: Indicates last reported status of sent emails. Default: `NOT_SET`. - enum: - NOT_SET: No status specified. This is the initial default 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. - name: createdDate | type: string | description: Date and time the email subscription was created. - name: updatedDate | type: string | description: Date and time the email subscription was last updated. - name: metadata | type: PagingMetadata | description: Metadata for the paginated results. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. ``` ### Examples ### Find Subscriptions for the Requested Email Addresses ```curl curl -X POST \ 'https://www.wixapis.com/email-marketing/v1/email-subscriptions/query' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ --data-binary '{ "filter": { "email": { "$in": ["email-1@query.com", "email-2@query.com"] } }, "paging": { "limit": 30, "offset": 30 } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.communication.EmailSubscriptionsService.queryEmailSubscriptions(filter, options) Description: 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: ```json { "filter": { "email": { "$in": ["me@my.com", "you@your.org"] } } } ``` To learn how to query email subscriptions, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: filter Method parameters: param name: filter | type: object | description: Filter options. Currently, querying is supported on the `email` field with the `$in` array filter. | required: true param name: options | type: QueryEmailSubscriptionsOptions none - name: paging | type: Paging | description: Pagination options. For more information, see [Pagination](https://dev.wix.com/api/rest/getting-started/pagination). - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. Return type: PROMISE - name: subscriptions | type: array | description: List of subscribed emails that matched the query options. - name: _id | type: string | description: Email subscription GUID. - name: email | type: string | description: Email address. - name: subscriptionStatus | type: Status | description: Indicates the recipient's opt-in or opt-out status for marketing emails. Default: `NOT_SET`. - enum: - UNKNOWN: Undefined status. - 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. - name: deliverabilityStatus | type: Status | description: Indicates last reported status of sent emails. Default: `NOT_SET`. - enum: - NOT_SET: No status specified. This is the initial default 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. - name: _createdDate | type: Date | description: Date and time the email subscription was created. - name: _updatedDate | type: Date | description: Date and time the email subscription was last updated. - name: metadata | type: PagingMetadata | description: Metadata for the paginated results. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. ``` ### Examples ### queryEmailSubscriptions ```javascript import { emailSubscriptions } from '@wix/email-subscriptions'; async function queryEmailSubscriptions(filter,options) { const response = await emailSubscriptions.queryEmailSubscriptions(filter,options); }; ``` ### queryEmailSubscriptions (with elevated permissions) ```javascript import { emailSubscriptions } from '@wix/email-subscriptions'; import { auth } from '@wix/essentials'; async function myQueryEmailSubscriptionsMethod(filter,options) { const elevatedQueryEmailSubscriptions = auth.elevate(emailSubscriptions.queryEmailSubscriptions); const response = await elevatedQueryEmailSubscriptions(filter,options); } ``` ### queryEmailSubscriptions (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { emailSubscriptions } from '@wix/email-subscriptions'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { emailSubscriptions }, // Include the auth strategy and host as relevant }); async function queryEmailSubscriptions(filter,options) { const response = await myWixClient.emailSubscriptions.queryEmailSubscriptions(filter,options); }; ``` ---