View and Edit

Variations (A/B Testing)

Legacy Newsletter is being retired 9/30/17.
Ready to migrate? Have Questions?
Please see our Migration Toolkit.

This module allows you to add new Variations to your drafted Marketing Emails. These Variations can be used in A/B testing (also sometimes called split testing).

add

Create a new Variation.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email in draft mode. The name of the Marketing Email you are adding Variations to.
variation Yes None The name of the Variation you will be adding.
subject Yes None The subject that will be used for the Variation being created.
text Yes None The text portion of the Marketing Email Variation being added.
html Yes None The html portion of the Marketing Email Variation being added.
type Yes Value must be either “text” or “html”. The Variation type, either plain text, or multipart-alternative text and html.
identity_name No Must be an existing Marketing Email Identity Identity name that is needed if the Marketing Email name does not already exist. Will be used to create a parent Marketing Email.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/add.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&type=html&variation=variation_name&subject=variation_subject&html=variation_body

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/variations/add.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&type=html&variation=variation_name&subject=variation_subject&html=variation_body

Response

1
2
3

<result>
   <message>success</message>
</result>

edit

Edit an existing Variation.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email with Variations added to it. The name of the Marketing Email you are editing Variations on.
variation Yes Must be an existing Variation The name of the Variation you will be editing.
newvariation No None The new name of the Variation.
subject No None The new subject of the Variation.
text No None The new text portion of the Marketing Email Variation.
html No None The new html portion of the Marketing Email Variation.
type No text/html The Variation type.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/edit.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&type=html&variation=existing_variation_name&newvariation=new_variation_name&subject=variation_subject&html=variation_body

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/variations/edit.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&type=html&variation=existing_variation_name&newvariation=new_variation_name&subject=variation_subject&html=variation_body

Response

1
2
3

<result>
   <message>success</message>
</result>

get

Retrieve the contents of an existing Variation.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email The name of the Marketing Email with existing Variations added to it.
variation Yes Must be an existing Variation The name of the Variation you would like the contents of.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/get.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=existing_variation_name

Response

1
2
3
4
5
6
7
8
9
10
11
12

{
  "name": "existing_variation_name",
  "timezone_id": null,
  "text": null,
  "is_winner": 0,
  "nl_type": 2,
  "html": null,
  "schedule_status": 3,
  "type": "html",
  "id": 2256144,
  "subject": "variation_subject"
}

Call

POST https://api.sendgrid.com/api/newsletter/variations/get.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=existing_variation_name

Response

1
2
3
4
5
6
7
8
9
10
11

<variation>
   <name>existing_variation_name</name>
   <timezone_id/>
   <text/>
   <is_winner>0</is_winner>
   <nl_type>2</nl_type>
   <schedule_status>3</schedule_status>
   <type>html</type>
   <id>2256144</id>
   <subject>variation_subject</subject>
</variation>

cancel

Cancels a current Variation send that is in progress.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email The name of the Marketing Email you wish to cancel, this cancels added Variations.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/cancel.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/variations/cancel.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft

Response

1
2
3

<result>
   <message>success</message>
</result>

delete

Delete the contents of an existing Variation.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email The name of the Marketing Email with existing Variations added to it.
variation No Must be an existing Variation The name of the Variation you would like to delete.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/delete.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=variation_to_delete

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/variations/delete.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=variation_to_delete

Response

1
2
3

<result>
   <message>success</message>
</result>

list

Retrieve a list of all Variations attached to a Marketing Email.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email The marketing email for which to list variations.
variation No Must be an existing Variation An optional list of names to check for.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/list.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=variation_to_find

Response

1

[{"name": "copy of SUZ5PT"},{"name": "5XZyGo"}]

Call

POST https://api.sendgrid.com/api/newsletter/variations/list.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=variation_to_find

Response

1
2
3

<result>
   <message>success</message>
</result>

pickwinner

Select the Variation you would like to send.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email Select the Marketing Email you are picking the winner of.
variation Yes Must be an existing Variation The winning Variation.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/pickwinner.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=variation_that_wins

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/variations/pickwinner.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&variation=variation_that_wins

Response

1
2
3

<result>
   <message>success</message>
</result>

schedule

Schedule a send time and percentage for your variations.

URI Parameter Required Requirements Description
name Yes Must be an existing Marketing Email Select the Marketing Email you would like to schedule Variation testing on.
percent Yes Must be a number 0-100 Percentage of the total recipients that will be emailed in the test.
delay No Must be numeric. The number of units specified by delay_type by which to delay the send.
delay_type No “minutes”, “hours”, or “days” The units used to specify the delay
date No Date / Time must be provided in ISO 8601 format (YYYY-MM-DDTHH:MM:SS+-HH:MM) Date / Time to schedule marketing email Delivery.
timezone No Must be an existing Variation An optional timezone of specific date (timezones are in the Olson Database name format).
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/variations/schedule.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&percent=50

Response

1
2
3

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/variations/schedule.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&name=existing_draft&percent=50

Response

1
2
3

<result>
   <message>success</message>
</result>