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 Body
Clear
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.
Data
Response Status
Response Body
Clear
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.
Data
Response Status
Response Body
Clear
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.
Data
Response Status
Response Body
Clear
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.
Data
Response Status
Response Body
Clear
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.
Data
Response Status
Response Body
Clear
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.
Data
Response Status
Response Body
Clear
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).
Data
Response Status
Response Body
Clear
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>