This endpoint allows you to manage entries in your Recipient Lists.

add

Add one or more emails to a Recipient List.

Parameter Required Requirements Description
list Yes Must be an existing Recipient List. The list which you are adding email addresses to.
data Yes Must be a valid JSON string matching the required format. Limited to a 1000 entries maximum. Specify the name, email address, and additional fields to add to the specified Recipient List.
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/lists/email/add.json
POST Data list=Test&data=%7B%22email%22%3A%22example%40gmail.com%22%2C%22name%22%3A%22example%22%7D&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "inserted": 1
}

Call

POST https://api.sendgrid.com/api/newsletter/lists/email/add.xml
POST Data list=Test&data=%7B%22email%22%3A%22example%40gmail.com%22%2C%22name%22%3A%22example%22%7D&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
<result>
   <inserted>1</inserted>
</result>

email and name are required and must be in the JSON string submitted in the data parameter. Further arbitrary keys may also be specified in the JSON string.

Examples

Add an email recipient to a list:

1
2
3
4
5
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/add.json \
     -d 'api_user=your_sendgrid_username' \
     -d 'api_key=your_sendgrid_password' \
     -d 'list=my_list' \
     -d 'data={"email":"address@domain.com","name":"contactName"}'

Add an email recipient with multiple data fields:

1
2
3
4
5
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/add.json \
     -d 'api_user=your_sendgrid_username' \
     -d 'api_key=your_sendgrid_password' \
     -d 'list=my_list' \
     -d 'data={"email":"grouch@trashcan.com","name":"Oscar","city":"New York","street":"123 Sesame St"}'

Add multiple email recipients to a list:

1
2
3
4
5
6
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/add.json \
     -d 'api_user=your_sendgrid_username' \
     -d 'api_key=your_sendgrid_password' \
     -d 'list=my_list' \
     -d 'data[]={"email":"address1@domain.com","name":"contactName1"}' \
     -d 'data[]={"email":"address2@domain.com","name":"contactName2"}'

get

Get the email addresses and associated fields for a Recipient List.

Parameter Required Requirements Description
list Yes Must be an existing Recipient List. The list which you are adding email addresses too.
email No Must be an email address or list of addresses. Optional email addresses to search for in the Recipient List.
unsubscribed No Must be set to 1 To retrieve a list of unsubscribed email addresses
Parameter Value Requirements Description

Call

GET https://api.sendgrid.com/api/newsletter/lists/email/get.json?list=Test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
4
5
6
[
  {
    "email": "dominic.may@sendgrid.com",
    "name": ""
  }
]

Call

GET https://api.sendgrid.com/api/newsletter/lists/email/get.xml?list=Test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
4
5
6
<emails>
   <email>
      <email>dominic.may@sendgrid.com</email>
      <name> </name>
   </email>
</emails>

count

Retrieve the number of entries on a list.

Parameter Required Requirements Description
list Yes Must be an existing Recipient List. The list which you are adding email addresses too.
Parameter Value Requirements Description

Call

GET https://api.sendgrid.com/api/newsletter/lists/email/count.json?list=Test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "count": 2
}

Call

GET https://api.sendgrid.com/api/newsletter/lists/email/count.xml?list=Test&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
<result>
   <count>2</count>
</result>

delete

Remove one or more emails from a Recipient List.

Parameter Required Requirements Description
list Yes Must be an existing Recipient List. The list which you are adding email addresses too.
email[] Yes Must be an email or emails in the Recipient List. Specify the email address or email addresses you wish to remove from the specified Recipient List. May list multiple addresses with multiple email[] parameters
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/api/newsletter/lists/email/delete.json
POST Data list=Test&email[]=example@gmail.com&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "removed": 1
}

Call

POST https://api.sendgrid.com/api/newsletter/lists/email/delete.xml
POST Data list=Test&email[]=example@gmail.com&api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
<result>
   <removed>1</removed>
</result>