Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Create List



API Overview

api-overview page anchor

Lists are static collections of Marketing Campaigns contacts. This API allows you to interact with the list objects themselves. To add contacts to a list, you must use the Contacts API.

You can also manage your lists using the Contacts menu in the Marketing Campaigns UI(link takes you to an external page). For more information about lists and best practices for building them, see "Building your Contact List".

(information)

Info

You can create a maximum of 1000 lists.


POST/v3/marketing/lists

Base url: https://api.sendgrid.com

This endpoint creates a new contacts list.

Once you create a list, you can use the UI to trigger an automation every time you add a new contact to the list.

A link to the newly created object is in _metadata.


Authentication

authentication page anchor
Property nameTypeRequiredDescription
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
SchemaExample
Property nameTypeRequiredDescriptionChild properties
namestringrequired

Your name for your list

Min length: 1Max length: 100
200400
SchemaExample
Property nameTypeRequiredDescriptionChild properties
idstring

The generated ID for your list.

Min length: 36Max length: 36

namestring

The name you gave your list.


contact_countinteger

The number of contacts currently stored on the list.


_metadataobject

Create List

create-list page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_21
const client = require('@sendgrid/client');
_21
client.setApiKey(process.env.SENDGRID_API_KEY);
_21
_21
const data = {
_21
"name": "list-name"
_21
};
_21
_21
const request = {
_21
url: `/v3/marketing/lists`,
_21
method: 'POST',
_21
body: data
_21
}
_21
_21
client.request(request)
_21
.then(([response, body]) => {
_21
console.log(response.statusCode);
_21
console.log(response.body);
_21
})
_21
.catch(error => {
_21
console.error(error);
_21
});


Rate this page: