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

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

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

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

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

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

<result>
   <message>error: reason</message>
</result>
    </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

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

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

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

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

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

<result>
   <message>error: reason</message>
</result>
    </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

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
7
8
9
10
11
12
13
14
//success
[
  {
    "list": "test"
  }
]

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

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
7
8
9
10
11
12
13
14
15
<?xml version="1.0" encoding="ISO-8859-1"?>

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

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

<result>
   <message>error: reason</message>
</result>
    </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

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

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

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

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

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

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