Skip to main content
CampaignsVersion: v3New

Upsert A/B Variation

POST/emails/locations/{locationId}/campaigns/emails/{campaignId}/variations/{index}

Get or create the campaign-owned document for A/B variation index (1 = version B, 2 = version C, ...) and optionally write its content. A missing variation is cloned from the campaign's current content. Version A (index 0) is the campaign itself: edit it with Update Email Campaign.

Use for an email-content A/B test (abTestConfig.testType=emailContent): call this once per variation index ≥ 1, then pass each returned documentId as abTestConfig.variations[index].documentId in Schedule Campaign. Never pass a template ID there.

Create versions in order (1, then 2, ...): an index whose previous version does not exist yet returns 400. Calls for the same campaign must be sequential; a call made while another is still running returns 409, so retry it. Allowed only while the campaign is draft, paused or cancelled; returns 409 otherwise. A paused campaign can only edit versions it already has: adding a new version returns 409 (cancel the campaign first). Returns 400 when index is outside 1-9 or editorContent is empty.

How an A/B test works (follow these steps in order):

  1. Version A is the campaign itself. Create it with Create Email Campaign and edit it with Update Email Campaign.
  2. Versions B, C, ... are stored inside the same campaign, not as separate campaigns or templates. Create or edit each one with Upsert A/B Variation (index 1 = B, 2 = C, ...; create them in order). Never create another campaign or template to make a version. Versions do not show in the campaign list, and the builder only shows them once the test is scheduled.
  3. Check the versions before sending: Get Email Campaign lists them in abVersions (with each documentId); Validate Email Campaign checks every version (issues carry variationIndex); Preview Email Campaign and Test Send Email Campaign take variationIndex to show or test-send one version. Use these to read a version; Upsert A/B Variation creates the version when it is missing.
  4. Start the test with Schedule Campaign abTestConfig: testType=emailContent with variations[index].documentId from abVersions (index 0 = version A, no documentId needed), or testType=subjectLine with one subject per version. Without abTestConfig the campaign sends version A only, and versions B, C, ... are never sent. The test group must give every version at least 10 contacts (see abTestConfig.testSize); otherwise Schedule Campaign returns 400.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:emails/campaigns.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3
Example:v3

Path Parameters

locationIdstringrequired

Location ID

Example:ve9EPM428h8vShlRW1KT
campaignIdstringrequired

Campaign ID returned by Create Email Campaign

Example:67f15c2ae99226d5bcccb8f3
indexintegerrequired

A/B variation index. 1 is version B, 2 is version C, and so on. Index 0 (version A) is the campaign itself: edit it with Update Email Campaign.

Possible values: >= 1 and <= 9

Example:1

Query Parameters

includeContentboolean

Set to true to include the variation’s current editorContent in the response.

Default:false
Example:false

Body

editorTypestring

Editor of the variation content. Send together with editorContent to write content; omit both to only create (or fetch) the variation document. Use the same editorType as the campaign.

Available optionshtmlbuildertext
Example:html
editorContentobject

Variation content. A string (HTML or plain text) when editorType is html or text; the design-editor JSON (elements, attrs, templateSettings) when editorType is builder.

allowEditorTypeChangeboolean

Content writes must keep the email’s editor: sending html/text for a design-editor (builder) email, or builder for an HTML/text email, is refused with 409 (code 6017) so the design is not replaced by accident. Set true only to convert the email to the other editor on purpose. Switching between html and text is always allowed. Design JSON over an email last saved in Design Editor 2.0 is always refused (409, code 6018); edit it in the app, or convert it with html and allowEditorTypeChange: true.

Default:false
Example:false
userIdstring

ID of the user performing this action

Example:507f1f77bcf86cd799439011

Response

Success

campaignIdstringrequired

Campaign ID

Example:67f15c2ae99226d5bcccb8f3
variationIndexnumberrequired

A/B variation index

Example:1
documentIdstringrequired

Campaign-owned document holding this variation’s content. Pass it as abTestConfig.variations[variationIndex].documentId in Schedule Campaign.

Example:67f15c2ae99226d5bcccb8f9
editorContentUrlstring

URL of the rendered variation HTML after this write. Issue a GET against it to see the result; a new URL is issued on every content save.

Example:https://firebasestorage.googleapis.com/v0/b/bucket/o/index.html?alt=media&token=abc
editorContentobject

Current variation content, returned only when includeContent=true.

designEditorV2boolean

Returned as true with includeContent=true when the variation was last saved in the new design editor (DnD 2.0, block format). editorContent is then omitted: this API reads and writes only the classic design-editor JSON, and the stored classic version is older.

Example:true
traceIdstring

Trace ID of the request

Example:019e4ef5-a65e-4198-8cf9-8e93dca9bda4