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.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/lists/add.json
POST Data list=test789&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/lists/add.xml
POST Data list=test789&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
<result>
   <message>success</message>
</result>

Additional columns may be added to a list at any time by specifying new column names when using the Email Add Endpoint.


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.
Parameter Value Requirements Description

Call

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

Response

1
2
3
{
  "message": "success"
}

Call

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

Response

1
2
3
<result>
   <message>success</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)
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/lists/get.json
POST Data list=test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
4
5
6
[
  {
    "id": 1,
    "list": "test"
  }
]

Call

POST https://api.sendgrid.com/api/newsletter/lists/get.xml
POST Data list=test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
4
5
6
<lists>
   <list>
      <id>1</id>
      <list>test</list>
   </list>
</lists>

delete

Remove a Recipient List from your account.

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

Call

POST https://api.sendgrid.com/api/newsletter/lists/delete.json
POST Data list=test5678&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/newsletter/lists/delete.xml
POST Data list=test5678&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
<result>
   <message>success</message>
</result>