Variations (A/B Testing) - SendGrid Documentation

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.


Data
Response Status
Response Headers
Response Body

JSON
XML

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

{
  "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

<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.


Data
Response Status
Response Headers
Response Body

JSON
XML

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

{
  "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

<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.


Data
Response Status
Response Headers
Response Body

JSON
XML

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

{
  "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

<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.


Data
Response Status
Response Headers
Response Body

JSON
XML

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

{
  "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

<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.


Data
Response Status
Response Headers
Response Body

JSON
XML

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

{
  "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

<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.


Data
Response Status
Response Headers
Response Body

JSON
XML

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

[{"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

<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.


Data
Response Status
Response Headers
Response Body

JSON
XML

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

{
  "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

<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).


Data
Response Status
Response Headers
Response Body

JSON
XML

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

{
  "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

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

Was this helpful?

Yes

Feedback

SendGrid Pricing Try SendGrid for Free Contact Us