Create and send A/B test newsletter - ExpertSender Help center

Creates and sends an email A/B test newsletter.

This method can be used to create:

an A/B test by content – one delivery date and multiple content versions,
an A/B test by date – one content version and multiple delivery dates.

Request#

POST https://api.esv2.com/v2/Api/AbTests

Request data format#

Data part of request for creating a new A/B test newsletter.

Data element children:

Element/attribute	Type	Description
Recipients	complex	Newsletter recipients’ information. Required.
Contents	array[complex]	Newsletter content versions. Required.
DeliverySettings	complex	Newsletter delivery settings. Optional.
WinnerSettings	complex	A/B test winner settings. Required.

Recipients element children:

Element/attribute	Type	Notes
SubscriberLists	array[integer]	Array of SubscriberList elements containing IDs of subscriber lists that newsletter will be sent to. Optional.*
SubscriberSegments	array[integer]	Array of SubscriberSegment elements containing IDs of subscriber segments that newsletter will be sent to. Optional.*
SeedLists	array[integer]	Array of SeedList elements containing IDs of seed lists used during shipment. Optional.*
SuppressionLists	array[integer]	Array of SuppressionList elements containing IDs of suppression lists that will be checked during shipment. Optional.
ExcludedLists	array[integer]	An array of SubscriberList elements containing the IDs of the subscriber lists to which the newsletter will be excluded from mailing. Optional.
ExcludedSegments	array[integer]	An array of SubscriberSegment elements containing the IDs of the subscriber segments to which the newsletter will be excluded from mailing. Optional.

* Newsletter has to have at least one subscriber list, subscriber segment or seed list specified. Empty recipients element will trigger appropriate error message.

Contents element children:

Element/attribute	Type	Description
Content	complex	Newsletter content version. Required.

The Contents collection must contain from 1 to 5 elements.

Content element children:

Element/attribute	Type	Description
ContentFromUrl	complex	Information about content to load from a remote server. Optional.
FromName	string	Sender name. Required.
FromEmail	string	Sender email address. Required.
ReplyToName	string	Reply-to name. Optional.
ReplyToEmail	string	Reply-to email address. Optional.
Subject	string	Message subject. Required.
Preheader	string	Message preheader. Optional.
Header	int	Header template ID. Optional.
Footer	int	Footer template ID. Optional.
Html	string	HTML content. Optional.
Plain	string	Plain text content. Optional.
AmpHtml	string	AMP HTML content. Optional.
GoogleAnalyticsTags	complex	Google Analytics tags. Optional.
CustomUtms	array[complex]	Custom UTM parameters. Optional.
Tags	array[string]	Message tags. Optional.
UrlIntegrations	complex	URL integrations. Optional.
Attachments	complex	Message attachments. Optional.

ContentFromUrl element children:

Element/attribute	Type	Notes
Url	string	URL address of imported file. Supported protocols are HTTP, HTTPS, FTP, FTPS and SFTP. E.g. ftp://www.domain.com/mycreative.zip
Username	string	Username used for authentication. Optional.
Password	string	Password used for authentication. Optional.
FtpAuth	string	Authentication method for secure FTP servers. Optional. Valid values are: None – FTP server does not support secure authentication (default) ExplicitTls – Explicit TLS/SSL authentication ExplicitSsl – Explicit SSL only authentication ImplicitSsl – Implicit SSL authentication
FtpUseActiveMode	boolean	If set to “true”, active mode will be used for FTP connections. Default value is “false” – passive connection mode will be used.

GoogleAnalyticsTags element children:

Element/attribute	Type	Notes
Campaign	string	Google Analytics tag “utm_campaign”. Optional.
Source	string	Google Analytics tag “utm_source”. Optional.
Content	string	Google Analytics tag “utm_content”. Optional.

Note: The remaining tag, “utm_medium” is by default specified as “Email”.

CustomUtms element children:

Element/attribute	Type	Notes
Name	string	The name of the custom UTM parameter. Maximum length: 255 characters. The name cannot be empty and must be unique. Do not reuse names already reserved by Google Analytics (e.g., utm_source, utm_medium, utm_campaign, utm_term, utm_content).
Value	string	The value assigned to the UTM parameter. Maximum length: 255 characters. The value cannot be empty.

UrlIntegrations element children:

Element/attribute	Type	Notes
ID	int	Id number of existing, not deleted integration. Required.

Attachment element children:

Element/attribute	Type	Notes
FileName	string	Attachment filename. E.g. “infosheet.pdf”. Should be unique (no 2 attachments should have the same filename). Required.
MimeType	string	File type according to MIME standards. E.g. “application/pdf”. If omitted, default MIME type will be used: “application/octet-stream”. Optional. MIME type can affect how email attachments are treated in different email clients, so it is advisable to always specify the correct type.*
Content	string	Attachment file content. Must be Base64 encoded.** See example requests. Required.

DeliverySettings element children:

Element/attribute	Type	Notes
DeliveryDates	complex	Delivery dates for the A/B test. Optional. If not specified, current date and time is used.
TimeZone	string	Time zone used with specified delivery date. Optional. Defaults to standard (unit) settings. List of valid values.
OverrideDeliveryCap	boolean	If set to “true”, newsletter will ignore any delivery frequency capping settings. Optional. Default is “false”.
ThrottlingMethod	string	Delivery throttling method. See below for description of different throttling methods. Optional. Default is “None”.
ManualThrottlingTime	int	Time (in hours) of manual delivery throttling. This setting is required if ThrottlingMethod was set to “Manual” and ignored in other cases.
TimeOptimizationPeriod	string	Time of delivery for Sending Time Optimization (STO). This setting is only used if ThrottlingMethod was set to “TimeOptimized” and is ignored in other cases. Valid values are: “24h” (24 hours – default) and “7d” (7 days).
Channels	array[complex]	Array of Channel elements describing delivery channels. Optional. If omitted, standard (unit) channel settings will be used to deliver the newsletter.
EnableOpenTrack	boolean	Indicates whether open tracking is enabled. Optional. Default value: true.
EnableClickTrack	boolean	Indicates whether click tracking is enabled. Optional. Default value: true.

DeliveryDates element children:

Element/attribute	Type	Notes
Date	datetime	Delivery date for the A/B test. Required.

For an A/B test by content:

Contents must contain more than one content version,
DeliveryDates must contain exactly one date,
if DeliveryDates is not provided, current date and time is used.

For an A/B test by date:

Contents must contain exactly one content version,
DeliveryDates must contain from 2 to 5 dates,
WinnerPickMethod must be set to Manual.

Channels element children:

Element/attribute	Type	Notes
Ip	string	Delivery channel IP address.
Percentage	integer	Portion (%) of emails that will be sent using this delivery channel.*

The sum of all Percentage values must equal 100.

WinnerSetting element children:

Element/attribute	Type	Notes
TestGroupsSize	integer	Percentage of recipients assigned to test groups. Required.
WinnerPickMethod	string	Method used to select the winning version. Available options are listed later in the documentation. Required.
SendWinnerAfterHours	integer	Number of hours after which the winning version should be sent. Used for winner selection methods other than Manual. Optional.

ThrottlingMethod element children:

Name	Behavior
None	Delivery will not be throttled. Newsletter will be sent as quickly as possible. This is a default method, but not recommended for delivering large volumes.
Auto	Automatic throttling. Delivery time will be automatically calculated, depending on number of recipients and unit settings.
Manual	Manual throttling. Delivery time is specified manually as a number of hours the whole delivery will take.
TimeOptimized	Sending Time Optimization (STO). Date of delivery will be calculated for each subscriber based on their previous performance over the next 24h/7d.

TimeTravel is not supported for A/B tests.

WinnerPickMethod element children:

Name	Behavior
OpenRate	Winning version is selected based on open rate.
ClickRate	Winning version is selected based on click rate.
GoalRate	Winning version is selected based on goal rate.
GoalValue	Winning version is selected based on goal value.
Manual	Winning version is selected manually.

Response#

Returns the ID of the created newsletter and IDs of all created content versions.

Response data format:

Element/attribute	Type	Notes
NewsletterId	integer	ID of the created A/B test newsletter.
VersionIds	complex	IDs of created content versions.

VersionIds element children:

Element/attribute	Type	Notes
VersionId	integer	Created content version ID.

Examples#

A/B test by content.

Request in XML format:

<ApiRequest>
  <ApiKey>test_api_key</ApiKey>
  <Data>
    <Recipients>
      <SubscriberLists>
        <SubscriberList>13689</SubscriberList>
        <SubscriberList>89</SubscriberList>
      </SubscriberLists>
      <SubscriberSegments>
        <SubscriberSegment>6614</SubscriberSegment>
      </SubscriberSegments>
      <SeedLists>
        <SeedList>13685</SeedList>
      </SeedLists>
      <SuppressionLists>
        <SuppressionList>1012</SuppressionList>
      </SuppressionLists>
    </Recipients>
    <Contents>
      <Content>
        <FromName>AB Test From 1</FromName>
        <FromEmail>sender@example.com</FromEmail>
        <ReplyToName>Reply 1</ReplyToName>
        <ReplyToEmail>reply1@example.com</ReplyToEmail>
        <Subject>AB Test Subject A</Subject>
        <Preheader>Preheader A</Preheader>
        <Header>3</Header>
        <Footer>1</Footer>
        <Html><![CDATA[<html><body>HTML A</body></html>]]></Html>
        <Plain>Plain A</Plain>
        <AmpHtml><![CDATA[<amp>AMP A</amp>]]></AmpHtml>
        <GoogleAnalyticsTags>
          <Campaign>spring_sale</Campaign>
          <Content>cta_a</Content>
          <Source>newsletter</Source>
          <Medium>email</Medium>
        </GoogleAnalyticsTags>
        <CustomUtms>
          <CustomUtm>
            <Name>utm_term1</Name>
            <Value>shoes</Value>
          </CustomUtm>
          <CustomUtm>
            <Name>utm_term2</Name>
            <Value>shirts</Value>
          </CustomUtm>
        </CustomUtms>
        <Tags>
          <Tag>promo</Tag>
          <Tag>ab-test</Tag>
        </Tags>
        <UrlIntegrations>
          <UrlIntegration>
            <Id>1</Id>
          </UrlIntegration>
          <UrlIntegration>
            <Id>3</Id>
          </UrlIntegration>
        </UrlIntegrations>
        <Attachments>
          <Attachment>
            <FileName>brochure.pdf</FileName>
            <MimeType>application/pdf</MimeType>
            <Content>AAECAw==</Content>
          </Attachment>
        </Attachments>
      </Content>
      <Content>
        <FromName>Example Sender B</FromName>
        <FromEmail>sender_b@example.com</FromEmail>
        <Subject>AB Test Subject B</Subject>
        <Html><![CDATA[<html><body>HTML B</body></html>]]></Html>
        <Plain>Plain B</Plain>
      </Content>
      <Content>
        <FromName>Example Sender C</FromName>
        <FromEmail>sender_c@example.com</FromEmail>
        <Subject>AB Test Subject C</Subject>
        <Html><![CDATA[<html><body>HTML C</body></html>]]></Html>
        <Plain>Plain C</Plain>
      </Content>
    </Contents>
    <DeliverySettings>
      <TimeZone>Central European Standard Time</TimeZone>
      <OverrideDeliveryCap>false</OverrideDeliveryCap>
      <ThrottlingMethod>None</ThrottlingMethod>
      <DeliveryDates>
        <Date>2026-04-24T12:30:00Z</Date>
      </DeliveryDates>
      <EnableOpenTrack>true</EnableOpenTrack>
      <EnableClickTrack>true</EnableClickTrack>
    </DeliverySettings>
    <WinnerSettings>
      <TestGroupsSize>50</TestGroupsSize>
      <WinnerPickMethod>OpenRate</WinnerPickMethod>
      <SendWinnerAfterHours>2</SendWinnerAfterHours>
    </WinnerSettings>
  </Data>
</ApiRequest>

Response:

<ApiResponse>
  <NewsletterId>125269</NewsletterId>
  <VersionIds>
    <VersionId>206284</VersionId>
    <VersionId>206285</VersionId>
    <VersionId>206286</VersionId>
  </VersionIds>
</ApiResponse>

A/B test by date.

Request:

<ApiRequest>
  <ApiKey>test_api_key</ApiKey>
  <Data>
    <Recipients>
      <SubscriberLists>
        <SubscriberList>13689</SubscriberList>
      </SubscriberLists>
    </Recipients>
    <Contents>
      <Content>
        <FromName>AB test sender</FromName>
        <FromEmail>sender@example.com</FromEmail>
        <Subject>AB test by date</Subject>
        <Html><![CDATA[<html><body>HTML</body></html>]]></Html>
        <Plain>Plain</Plain>
      </Content>
    </Contents>
    <DeliverySettings>
      <TimeZone>Central European Standard Time</TimeZone>
      <ThrottlingMethod>None</ThrottlingMethod>
      <DeliveryDates>
        <Date>2026-04-24T10:00:00Z</Date>
        <Date>2026-04-24T14:00:00Z</Date>
      </DeliveryDates>
      <EnableOpenTrack>true</EnableOpenTrack>
      <EnableClickTrack>true</EnableClickTrack>
    </DeliverySettings>
    <WinnerSettings>
      <TestGroupsSize>50</TestGroupsSize>
      <WinnerPickMethod>Manual</WinnerPickMethod>
      <SendWinnerAfterHours>2</SendWinnerAfterHours>
    </WinnerSettings>
  </Data>
</ApiRequest>

Response:

<ApiResponse>
  <NewsletterId>125270</NewsletterId>
  <VersionIds>
    <VersionId>206287</VersionId>
    <VersionId>206288</VersionId>
  </VersionIds>
</ApiResponse>