On this page

Delete a list

API Overview

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. For more information about lists and best practices for building them, see "Building your Contact List".

Operation overview

DELETE/v3/marketing/lists/{id}

Base url: https://api.sendgrid.com (The Twilio SendGrid v3 API)

This endpoint allows you to deletes a specific list.

Optionally, you can also delete contacts associated to the list. The query parameter, delete_contacts=true, will delete the list and start an asynchronous job to delete associated contacts.

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstringrequired

Default: Bearer <<YOUR_API_KEY_HERE>>

Path parameters

Property nameTypeRequiredDescription

idstringrequired

The ID of the list on which you want to perform the operation.

Query string

Property nameTypeRequiredDescription

delete_contactsboolean

Optional

Flag indicates that all contacts on the list are also to be deleted.

Default: false

Responses

200204404

The delete has been accepted and is processing.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

job_idstring

job_id of the async job

Schema

string

The delete has been processed.

Delete a list

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const id = "ZGkrHSypTsudrGkmdpJJ";
5
6const request = {
7  url: `/v3/marketing/lists/${id}`,
8  method: "DELETE",
9};
10
11client
12  .request(request)
13  .then(([response, body]) => {
14    console.log(response.statusCode);
15    console.log(response.body);
16  })
17  .catch((error) => {
18    console.error(error);
19  });