Emails

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

1

http://sendgrid.com/api/newsletter/lists/email/add.json?list=Test&data=%7B%22email%22%3A%22example%40gmail.com%22%2C%22name%22%3A%22example%22%7D&api_user=SGusername&api_key=SGpassword

Response: Success

1
2
3

{
  "inserted": 1
}

Response: Error

1
2
3
4
5
6

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

Call

1

http://sendgrid.com/api/newsletter/lists/email/add.xml?list=Test&data=%7B%22email%22%3A%22example%40gmail.com%22%2C%22name%22%3A%22example%22%7D&api_user=SGusername&api_key=SGpassword

Response: Success

1
2
3
4
5

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

<result>
   <inserted>1</inserted>
</result>

Response: Error

1
2
3
4
5

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

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

Response

Success: (X records inserted)

1

{"inserted": X}

Examples

Add an email recipient to a list:

1

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

Add an email recipient with multiple data fields:

1

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

Add multiple email recipients to a list:

1

#curl -d 'api_user=username&api_key=password&list=my_list&data[]={"email":"address1@domain.com","name":"contactName1"}&data[]={"email":"address2@domain.com","name":"contactName2"}' https://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

1

http://sendgrid.com/api/newsletter/lists/email/get.json?list=Test&api_user=SGusername&api_key=SGpassword

Response: Success

1
2
3
4
5
6

[
  {
    "email": "dominic.may@sendgrid.com",
    "name": ""
  }
]

Response: Error

1
2
3
4
5
6

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

Call

1

http://sendgrid.com/api/newsletter/lists/email/get.xml?list=Test&api_user=SGusername&api_key=SGpassword

Response: Success

1
2
3
4
5
6
7
8
9

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

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

Response: Error

1
2
3
4
5

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

<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

1

http://sendgrid.com/api/newsletter/lists/email/delete.json?list=Test&email=example%40gmail.com&api_user=SGusername&api_key=SGpassword

Response: Success

1
2
3

{
  "removed": 1
}

Response: Error

1
2
3
4
5
6

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

Call

1

http://sendgrid.com/api/newsletter/lists/email/delete.xml?list=Test&email=example%40gmail.com&api_user=SGusername&api_key=SGpassword

Response: Success

1
2
3
4
5

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

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

Response: Error

1
2
3
4
5

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

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