Lists

This endpoint allows you to manage and create Recipient Lists associated with the Marketing Email feature.

add

Create a new Recipient List.

Parameter Required Requirements Description
list Yes None Create a Recipient List with this name.
name No None Specify the column name for the ‘name’ associated with email addresses.
columnname No None Specify additional column names. The format needs to be 
&columnname=columnname
[columnname] will be the replacement tag.

Call

1

http://sendgrid.com/api/newsletter/lists/add.json?list=test789&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3

{
  "message": "success"
}

Response: Error

1
2
3
4
5
6

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

Call

1

http://sendgrid.com/api/newsletter/lists/add.xml?list=test789&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3
4
5

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

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

Response: Error

1
2
3
4
5

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

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

edit

Rename a Recipient List.

Parameter Required Requirements Description
list Yes Must be an existing Recipient List. This is the name of the Recipient List to be renamed.
newlist Yes None Specify the new name for the Recipient List.

Call

1

http://sendgrid.com/api/newsletter/lists/edit.json?list=test7890&newlist=test567&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3

{
  "message": "success"
}

Response: Error

1
2
3
4
5
6

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

Call

1

http://sendgrid.com/api/newsletter/lists/edit.xml?list=test7890&newlist=test567&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3
4
5

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

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

Response: Error

1
2
3
4
5

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

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

get

List all Recipient Lists on your account, or check if a particular List exists.

Parameter Required Requirements Description
list No None Check for this particular list. (To list all Recipient Lists on your account exclude this parameter)

Call

1

http://sendgrid.com/api/newsletter/lists/get.json?list=test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3
4
5

[
  {
    "list": "test"
  }
]

Response: Error

1
2
3
4
5
6

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

Call

1

http://sendgrid.com/api/newsletter/lists/get.xml?list=test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3
4
5
6
7

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

<lists>
   <list>
      <list>test</list>
   </list>
</lists>

Response: Error

1
2
3
4
5

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

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

delete

Remove a Recipient List from your account.

Parameter Required Requirements Description
list Yes Must be an existing Recipient List. Remove this Recipient List.

Call

1

http://sendgrid.com/api/newsletter/lists/delete.json?list=test5678&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3

{
  "message": "success"
}

Response: Error

1
2
3
4
5
6

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

Call

1

http://sendgrid.com/api/newsletter/lists/delete.xml?list=test5678&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response: Success

1
2
3
4
5

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

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

Response: Error

1
2
3
4
5

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

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