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 too.
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.

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

//error
{
  "message": "error",
  "error": "error message"
}

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

<result>
   <inserted>1</inserted>
</result>
	  <h4>Response: Error</h4>
<?xml version="1.0" encoding="ISO-8859-1"?>

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

Examples

Add an email recipient to a list:

1
#curl -d 'api_user=your_sendgrid_username&api_key=your_sendgrid_password&list=my_list&data={"email":"address@domain.com","name":"contactName"}' https://api.sendgrid.com/api/newsletter/lists/email/add.json

Add an email recipient with multiple data fields:

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

Add multiple email recipients to a list:

1
#curl -d 'api_user=your_sendgrid_username&api_key=your_sendgrid_password&list=my_list&data[]={"email":"address1@domain.com","name":"contactName1"}&data[]={"email":"address2@domain.com","name":"contactName2"}' https://api.sendgrid.com/api/newsletter/lists/email/add.json

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 you are searching.
email No Must be an email address or list of addresses. Optional email addresses to search for in the Recipient List.

Call

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//success
[
  {
    "email": "dominic.may@sendgrid.com",
    "name": ""
  }
]

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

Call

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?xml version="1.0" encoding="ISO-8859-1"?>

<emails>
   <email>
      <email>dominic.may@sendgrid.com</email>
      <name>
    </name>
   </email>
</emails>

<!-- error -->

<result>
   <message>error: reason</message>
</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 removing email addresses from.
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.

Call

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
//success
{
  "removed": 1
}

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

Call

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- success -->
<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <removed>1</removed>
</result>

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

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