About the Campaign API

With the Campaign API you can create and manage email marketing campaigns for a Wix site, including composing content, publishing to contacts, and tracking engagement statistics.

With the Campaign API, you can:

• Create campaigns from editor data.
• Retrieve information about a campaign.
• List all campaigns for a site.
• Publish a campaign and send it to contacts.
• Send a test email to preview how a campaign will look in an inbox.
• Reschedule a scheduled campaign.
• Resend a campaign to recipients who didn't open the original email.
• Reuse an existing campaign to create a draft copy.
• Retrieve statistics and recipients for a campaign. Statistics are available only for published campaigns.

Creating a campaign

Use Create Campaign to create a new draft campaign from editor data. Pass the composerDataJson field with the campaign's content and set campaignEditorType to match the format you're using.

The composerDataJson field supports three formats, determined by campaignEditorType:

• WEB: Wix proprietary JSON format for the classic drag-and-drop editor.
• MOBILE: A subset of the WEB format for the classic mobile editor.
• MJML: MJML markup wrapped in a JSON object under key "mjml".

Passing a format that doesn't match the specified campaignEditorType doesn't return an immediate error, but causes the campaign to fail silently when previewing or sending. MJML is the most straightforward format to generate programmatically.

You can also set an optional emailPreheader when creating or updating a campaign. This is short preview text shown after the subject line in many email clients and can improve open rates.

After creating a campaign, you can update its content with Update Composer or render a preview with Preview Campaign.

The campaignEditorType can't be changed after a campaign is created. Passing a composerDataJson in a different format when calling Update Composer causes a silent failure when sending or previewing.

If your campaign content contains dynamic placeholders for personalization, pass a placeholders map to Preview Campaign to resolve those tokens in the preview. Set default placeholder values in composer.defaultValues to use as fallbacks when actual recipient values aren't available.

To retrieve a campaign's subject line, use Get Composer. The emailSubject field on the Campaign object is deprecated.

Publishing a campaign

To publish a campaign, sender details must be set up for the site. Call Identify Sender Address to determine which email address will appear as the "From" address.

Call Publish Campaign to send the campaign:

• Pass emailDistributionOptions to distribute the campaign by email to contacts. Campaigns can only be sent to Wix site contacts, defined by contact IDs, contact labels, or segment IDs.
• Omit emailDistributionOptions to publish the campaign as a landing page only, without sending any emails. This decision is permanent — once published as a landing page only, the campaign can't be sent by email. Use Reuse Campaign to create a new draft copy if you need to send emails later.

The response always includes a landingPageUrl that can be shared on social media, regardless of whether emails are sent.

You can schedule a campaign to send at a future time by passing emailDistributionOptions.sendAt. The scheduled time must be at least 30 minutes in the future. Use Pause Scheduling and Reschedule to adjust a scheduled campaign before it sends.

Email distribution process

After publishing with email distribution, the campaign moves through the following distributionStatus values:

1. SAMPLING: A small subset of the audience receives the email first. The system checks for issues such as spam-trap hits or excessive bounce rates.
2. SENDING: Sampling passed and the email is being sent to the full audience.
3. DISTRIBUTED: The email has been sent to all recipients.
4. TERMINATED: Sampling failed due to quality issues. The campaign is stopped before reaching the full audience. A terminated campaign can be reused with Reuse Campaign to create a new draft for republishing.
5. REJECTED: The campaign was identified as abusive and blocked before sending.

Paused campaigns and audience retrieval

When a scheduled campaign is paused with Pause Scheduling, the original audience settings are preserved. Use Get Audience to retrieve those audience settings so you can pass them back when republishing the campaign.

Resending to non-openers

Use Resend to Non-Openers to send a follow-up to recipients who didn't open the original campaign email. The following conditions must be met:

• The original campaign was sent at least 24 hours ago.
• There are recipients who received the email but didn't open it.
• Resend to Non-Openers hasn't already been called for this campaign.

An optional different subject line can be passed to improve open rates on the follow-up.

Before you begin

It's important to note the following points before starting to code:

• Each site has an email quota per billing period that depends on the email marketing plan.
• The site's email marketing account must be active. A site owner can be blocked from using email marketing for not complying with the Wix Email Marketing Terms of Use. Use Get Account Details to check the account status before publishing.
• Sender details must be configured before publishing a campaign.
• Campaigns can only be sent to Wix site contacts.

Use cases

• A/B test email subject lines

Terminology

• Campaign: A marketing message distributed to an audience via email and a public landing page.
• Composer: The editor data for a campaign, containing the email content in composerDataJson and the email subject.
• Campaign editor type: Determines the format of composerDataJson. Options are WEB, MOBILE, MJML.
• Preheader: Short preview text shown after the subject line in many email clients. Set via emailPreheader on Create Campaign or Update Composer.
• Sampling: The initial phase of email distribution where a small subset of recipients receive the email first, before it's sent to the full audience.
• Audience: The group of recipients targeted by a campaign, defined by contact IDs, contact labels, or segment IDs.
• Campaign scheduling: Setting a future date and time for a campaign to be sent. Requires at least 30 minutes' notice and a plan that supports scheduling.
• Label: A tag used to organize and group site contacts, which can be used to define a campaign audience.
• Landing page: A public web page generated for each published campaign. Available regardless of whether the campaign is distributed by email.