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.

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 No If the type parameter is set to “html” this parameter is required. 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.

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
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
4
5
6
7
8
9
10
11
12
<?xml version="1.0" encoding="ISO-8859-1"?>

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

<!-- error -->
<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

edit

Edit an existing Variation.

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.

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
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
4
5
6
7
8
9
10
11
12
<?xml version="1.0" encoding="ISO-8859-1"?>

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

<!-- error -->
<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

get

Retrieve the contents of an existing Variation.

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.

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
13
14
15
16
17
18
19
20
21
//success
{
    "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"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
12
13
14
15
16
17
18
19
20
<?xml version='1.0' encoding='UTF-8'?><variation>
  <name>existing_variation_name</name>
  <timezone_id/>
  <text/>
  <is_winner>0</is_winner>
  <nl_type>2</nl_type>
  <html/>
  <schedule_status>3</schedule_status>
  <type>html</type>
  <id>2256144</id>
  <subject>variation_subject</subject>
</variation>

<!-- error -->

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

cancel

Cancels a current Variation send that is in progress.

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.

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
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="ISO-8859-1"?>

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

<!-- error -->

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

delete

Delete the contents of an existing Variation.

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.

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
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="ISO-8859-1"?>

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

<!-- error -->

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

list

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

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.

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
2
3
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="ISO-8859-1"?>

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

<!-- error -->

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

pickwinner

Select the Variation you would like to send.

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

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
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="ISO-8859-1"?>

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

<!-- error -->

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

schedule

Schedule a send time and percentage for your variations.

Parameter Required Requirements Description
name Yes Must be an existing Marketing Email Select the Marketing Email you’de 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 Must be an existing Variation An optional list of names’s to check for.
timezone No Must be an existing Variation An optional timezone of specific date (timezones are in the Olson Database name format).

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
4
5
6
7
8
9
10
11
12
//success
{
  "message": "success"
}

//error
{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

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
4
5
6
7
8
9
10
11
12
13
<?xml version="1.0" encoding="ISO-8859-1"?>

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

<!-- error -->

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>