> 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 # UpsertEmailSubscription # Package: communication # Namespace: EmailSubscriptionsService # Method link: https://dev.wix.com/docs/api-reference/crm/communication/email-subscriptions/upsert-email-subscription.md ## Permission Scopes: Manage Email Subscriptions: SCOPE.DC-MANAGE.EMAIL-SUBSCRIPTIONS ## Introduction Updates or creates an email subscription for the requested email. An email subscription is returned in the response whether it was updated or created. --- ## REST API ### Schema ``` Method: upsertEmailSubscription Description: Updates or creates an email subscription for the requested email. An email subscription is returned in the response whether it was updated or created. URL: https://www.wixapis.com/email-marketing/v1/email-subscriptions Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: subscription.email Method parameters: param name: subscription | type: EmailSubscription - name: email | type: string | description: Email address. | required: true - 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. Return type: UpsertEmailSubscriptionResponse - name: subscription | type: EmailSubscription | description: Updated or created email subscription. - 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. ``` ### Examples ### Update or Create an Email Subscription ```curl curl -X POST \ 'https://www.wixapis.com/email-marketing/v1/email-subscriptions' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ --data-binary '{ "subscription": { "email": "email@test.com", "subscriptionStatus": "SUBSCRIBED", "deliverabilityStatus": "VALID" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.communication.EmailSubscriptionsService.upsertEmailSubscription(options) Description: Updates or creates an email subscription for the requested email. An email subscription is returned in the response whether it was updated or created. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: options.subscription.email Method parameters: param name: options | type: UpsertEmailSubscriptionOptions none - name: subscription | type: EmailSubscription | description: Email subscription to update or create. - name: email | type: string | description: Email address. | required: true - 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. Return type: PROMISE - name: subscription | type: EmailSubscription | description: Updated or created email subscription. - 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. ``` ### Examples ### upsertEmailSubscription ```javascript import { emailSubscriptions } from '@wix/email-subscriptions'; async function upsertEmailSubscription(options) { const response = await emailSubscriptions.upsertEmailSubscription(options); }; ``` ### upsertEmailSubscription (with elevated permissions) ```javascript import { emailSubscriptions } from '@wix/email-subscriptions'; import { auth } from '@wix/essentials'; async function myUpsertEmailSubscriptionMethod(options) { const elevatedUpsertEmailSubscription = auth.elevate(emailSubscriptions.upsertEmailSubscription); const response = await elevatedUpsertEmailSubscription(options); } ``` ### upsertEmailSubscription (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 upsertEmailSubscription(options) { const response = await myWixClient.emailSubscriptions.upsertEmailSubscription(options); }; ``` ---