Please refer to our API Key page for information on how to authenticate and use these endpoints.

Custom Fields Lists Recipients Segments

Contacts API

Treat recipient IDs as opaque values. The id value returned by recipient endpoints should be passed exactly as returned to endpoints that require a recipient id.

Recipient IDs are generated by encoding the recipient’s email address in Base64 format. You can use any Base64 encoder/decoder, for example https://www.base64encode.org/, to convert a recipient ID to the recipient’s email address (and vice versa).

Custom Fields

Create a Custom Field [POST]

Request

1
POST https://api.sendgrid.com/v3/contactdb/custom_fields HTTP/1.1
Request Body
1
2
3
4
{
  "name": "pet",
  "type": "text"
}

Response

1
2
3
4
5
6
HTTP/1.1 201
{
  "id": 1,
  "name": "pet",
  "type": "text"
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
Returned if request body is invalid JSON
typeReturned if custom field type is invalid or not provided
nameReturned if custom field name is not provided
You can create a maximum of 120 custom fields.

List All Custom Fields [GET]

Request

1
GET https://api.sendgrid.com/v3/contactdb/custom_fields HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
HTTP/1.1 200
{
  "custom_fields": [
    {
      "id": 1,
      "name": "birthday",
      "type": "date"
    },
    {
      "id": 2,
      "name": "middle_name",
      "type": "text"
    },
    {
      "id": 3,
      "name": "favorite_number",
      "type": "number"
    }
  ]
}

Retrieve a Custom Field [GET]

URI Parameter Required Requirements Description
custom_field_id Yes number The id of the custom field

Request

1
GET https://api.sendgrid.com/v3/contactdb/custom_fields/{custom_field_id} HTTP/1.1

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "id": 1,
  "name": "pet",
  "type": "text"
}
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
custom_field_idReturned if custom_field_id does not exist

Delete a Custom Field [DELETE]

URI Parameter Required Requirements Description
custom_field_id Yes number The id of the custom field

Request

1
DELETE https://api.sendgrid.com/v3/contactdb/custom_fields/{custom_field_id} HTTP/1.1

Response

1
HTTP/1.1 202
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
idReturned if custom_field_id is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
custom_field_idReturned if custom_field_id does not exist

Reserved Fields

List fields that are reserved and can't be used for custom field names. [GET]

Request

1
GET https://api.sendgrid.com/v3/contactdb/reserved_fields HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
HTTP/1.1 200
{
  "reserved_fields": [
    {
      "name": "first_name",
      "type": "text"
    },
    {
      "name": "last_name",
      "type": "text"
    },
    {
      "name": "email",
      "type": "text"
    },
    {
      "name": "created_at",
      "type": "date"
    },
    {
      "name": "updated_at",
      "type": "date"
    },
    {
      "name": "last_emailed",
      "type": "date"
    },
    {
      "name": "last_clicked",
      "type": "date"
    },
    {
      "name": "last_opened",
      "type": "date"
    },
    {
      "name": "my_custom_field",
      "type": "text"
    },
    {
      "name": "lists",
      "type": "set"
    },
    {
      "name": "campaigns",
      "type": "set"
    }
  ]
}

Lists

All recipient IDs are a URL-safe base64 encoding of the recipient's lower cased email address; for example if a recipient's email is foo@example.com, their recipient ID is Zm9vQGV4YW1wbGUuY29t.

Create a List [POST]

Request

1
POST https://api.sendgrid.com/v3/contactdb/lists HTTP/1.1
Request Body
1
2
3
{
  "name": "listname"
}

Response

1
2
3
4
5
6
HTTP/1.1 201
{
  "id": 1,
  "name": "listname",
  "recipient_count": 0
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
nameReturned if list name is a duplicate of an existing list or segment
nameReturned if list name is not a string
Returned if request body is invalid JSON

List All Lists [GET]

Returns an empty list if you GET and no lists exist on your account.

Request

1
GET https://api.sendgrid.com/v3/contactdb/lists HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200
{
  "lists": [
    {
      "id": 1,
      "name": "the jones",
      "recipient_count": 1
    }
  ]
}

Delete Multiple lists [DELETE]

Request

1
DELETE https://api.sendgrid.com/v3/contactdb/lists HTTP/1.1
Request Body
1
2
3
4
5
[
  1,
  2,
  3
]

Response

1
HTTP/1.1 204
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
idReturned if all list ids are not valid

Retrieve a List [GET]

URI Parameter Required Requirements Description
list_id Yes number The ID of the list

Request

1
GET https://api.sendgrid.com/v3/contactdb/lists/{list_id} HTTP/1.1

Response

1
2
3
4
5
6
HTTP/1.1 200
{
  "id": 1,
  "name": "listname",
  "recipient_count": 0
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
list_idReturned if list_id is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
list_idReturned if list_id does not exist

Update a List [PATCH]

URI Parameter Required Requirements Description
list_id Yes number The ID of the list

Request

1
PATCH https://api.sendgrid.com/v3/contactdb/lists/{list_id} HTTP/1.1
Request Body
1
2
3
{
  "name": "newlistname"
}

Response

1
HTTP/1.1 200
URI Parameter Required Requirements Description
list_id Yes number The ID of the list

Request

1
PATCH https://api.sendgrid.com/v3/contactdb/lists/{list_id} HTTP/1.1

Response

1
HTTP/1.1 400
URI Parameter Required Requirements Description
list_id Yes number The ID of the list

Request

1
PATCH https://api.sendgrid.com/v3/contactdb/lists/{list_id} HTTP/1.1

Response

1
HTTP/1.1 404

Delete a List [DELETE]

URI Parameter Required Requirements Description
delete_contacts No boolean True to delete all contacts on the list in addition to deleting the list
Default: true

Request

1
DELETE https://api.sendgrid.com/v3/contactdb/lists/{list_id} HTTP/1.1

Response

1
HTTP/1.1 202
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
list_idReturned if list_id is not valid
delete_contactsReturned if delete_contacts is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
list_idReturned if list_id does not exist

List Recipients on a List [GET]

URI Parameter Required Requirements Description
list_id Yes integer The ID of your list
page No integer Page index of first recipient to return (must be a positive integer)
Default: 1
page_size No integer Number of recipients to return at a time (must be a positive integer between 1 and 1000)
Default: 100

Request

1
GET https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients?page_size=100&page=1 HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
HTTP/1.1 200
{
  "recipients": [
    {
      "created_at": 1422395108,
      "email": "eexampexample@example.com",
      "first_name": "Ed",
      "id": "YUBh",
      "last_clicked": null,
      "last_emailed": null,
      "last_name": null,
      "last_opened": null,
      "updated_at": 1422395108
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
list_idReturned if list_id is not a valid integer
pageReturned if page is not a valid integer
pageReturned if page is less than 1
page_sizeReturned if page_size is not a valid integer
page_sizeReturned if page_size is less than 1 or greater than 1000
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
list_idReturned if list_id does not exist

Add a Single Recipient to a List [POST]

Individual recipients may be added to a list one at a time with a limit of 1000 requests per second, where one recipient is added to the list per request.
URI Parameter Required Requirements Description
list_id Yes number The ID of your list
recipient_id Yes string The ID of your existing recipient

Request

1
POST https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients/{recipient_id} HTTP/1.1

Response

1
HTTP/1.1 201
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
list_idReturned if list_id is invalid
recipient_idReturned if recipient_id is invalid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
list_idReturned if list_id does not exist
recipient_idReturned if recipient_id does not exist

Delete a Single Recipient from a Single List [DELETE]

URI Parameter Required Requirements Description
list_id Yes number The ID of your list
recipient_id Yes string The ID of your existing recipient

Request

1
DELETE https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients/{recipient_id} HTTP/1.1

Response

1
HTTP/1.1 204
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
list_idReturned if list_id is not valid
recipient_idReturned if recipient_id is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
list_idReturned if list_id does not exist
recipient_idReturned if recipient_id does not exist

Add Multiple Recipients to a List [POST]

Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints.

The rate at which recipients may be added to a list is limited to 1 request per second. Recipients may be added in batches of 1000.

URI Parameter Required Requirements Description
list_id Yes number The ID of your list

Request

1
POST https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients HTTP/1.1
Request Body
1
2
3
4
[
  "recipient_id1",
  "recipient_id2"
]

Response

1
HTTP/1.1 201
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
list_idReturned if list_id is not a valid integer
Returned if no valid recipient ids were passed
Returned if no recipients were added
Returned if request body is invalid JSON
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
list_idReturned if list_id does not exist
errorsReturned with message `No more pages` when at the end of the list

Recipients

If you make a request to upload a duplicate recipient and your request would make no change to the original recipient, the original recipient will remain unchanged and its index will be added to the unmodified_indices list.

Add Single Recipient [POST]

The rate at which recipients may be uploaded is limited to 3 requests every 2 seconds. Recipients may be uploaded in batches of 1000 per request. This results in a maximum upload rate of 1500 recipients per second.

Request

1
POST https://api.sendgrid.com/v3/contactdb/recipients HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
[
  {
    "email": "example@example.com",
    "last_name": "Jones",
    "pet": "Fluffy",
    "age": 25
  }
]

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 201
{
  "error_count": 0,
  "error_indices": [

  ],
  "unmodified_indices": [

  ],
  "new_count": 1,
  "persisted_recipients": [
    "am9uZXNAZXhhbXBsZS5jb20="
  ],
  "updated_count": 0
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
Returned if request body is not valid json

Add Multiple Recipients [POST]

Request

1
POST https://api.sendgrid.com/v3/contactdb/recipients HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[
  {
    "email": "example@example.com",
    "last_name": "Jones",
    "pet": "Fluffy",
    "age": 25
  },
  {
    "email": "milleexampexample@example.com",
    "last_name": "Miller",
    "pet": "FrouFrou",
    "age": 32
  },
  {
    "email": "invalid_email",
    "last_name": "Smith",
    "pet": "Spot",
    "age": 17
  },
  {
    "email": "pre-existing_email@example.com"
  }
]

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
HTTP/1.1 201
{
  "error_count": 1,
  "error_indices": [
    2
  ],
  "unmodified_indices": [
    3
  ],
  "new_count": 2,
  "persisted_recipients": [
    "YUBh",
    "bWlsbGVyQG1pbGxlci50ZXN0"
  ],
  "updated_count": 0,
  "errors": [
    {
      "message": "Invalid email.",
      "error_indices": [
        2
      ]
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
Returned if request body is not valid json

Update Recipient [PATCH]

Updates one or more recipients. The body is a list of recipient objects.

Request

1
PATCH https://api.sendgrid.com/v3/contactdb/recipients HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
[
  {
    "email": "example@example.com",
    "last_name": "Jones"
  },
  {
    "email": "pre-existing_email@example.com"
  }
]

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 201
{
  "error_count": 0,
  "error_indices": [

  ],
  "unmodified_indices": [
    1
  ],
  "new_count": 0,
  "persisted_recipients": [
    "am9uZXNAZXhhbXBsZS5jb20="
  ],
  "updated_count": 1
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
Returned if request body is not valid json

Delete Recipient [DELETE]

Deletes one or more recipients. The body is a list of recipient ids to delete.

Request

1
DELETE https://api.sendgrid.com/v3/contactdb/recipients HTTP/1.1
Request Body
1
2
3
4
[
  "recipient_id1",
  "recipient_id2"
]

Response

1
HTTP/1.1 204
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
Returned if no recipients are deleted
Returned if all of the provided recipient ids are invalid
Returned if request body is not valid json

Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.

List Recipients [GET]

URI Parameter Required Requirements Description
page No integer Page index of first recipients to return (must be a positive integer)
Default: 1
page_size No integer Number of recipients to return at a time (must be a positive integer between 1 and 1000)
Default: 100

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients?page_size=100&page=1 HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
HTTP/1.1 200
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "example@example.com",
      "first_name": null,
      "id": "YUBh",
      "last_clicked": null,
      "last_emailed": null,
      "last_name": "Jones",
      "last_opened": null,
      "updated_at": 1422313790,
      "custom_fields": [
        {
          "id": 23,
          "name": "pet",
          "value": "Indiana",
          "type": "text"
        }
      ]
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
pageReturned if page is not a valid integer
pageReturned if page is less than 1
page_sizeReturned if page_size is not a valid integer
page_sizeReturned if page_size is less than 1 or greater than 1000
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
errorsReturned with message `No more pages` when at the end of the list

Retrieve a Recipient [GET]

URI Parameter Required Requirements Description
recipient_id Yes number The ID of the recipient

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients/{recipient_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
HTTP/1.1 200
{
  "created_at": 1422313607,
  "email": "example@example.com",
  "first_name": null,
  "id": "YUBh",
  "last_clicked": null,
  "last_emailed": null,
  "last_name": "Jones",
  "last_opened": null,
  "updated_at": 1422313790,
  "custom_fields": [
    {
      "id": 23,
      "name": "pet",
      "value": "Indiana",
      "type": "text"
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
recipient_idReturned if recipient_id is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
recipient_idReturned if record for recipient id does not exist

Delete a Recipient [DELETE]

URI Parameter Required Requirements Description
recipient_id Yes number The ID of the recipient

Request

1
DELETE https://api.sendgrid.com/v3/contactdb/recipients/{recipient_id} HTTP/1.1

Response

1
HTTP/1.1 204
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
recipient_idReturned if recipient_id is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
recipient_idReturned if record for recipient id does not exist

Get the Lists the Recipient Is On [GET]

URI Parameter Required Requirements Description
recipient_id Yes string The ID of the recipient

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients/{recipient_id}/lists HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200
{
  "lists": [
    {
      "id": 1,
      "name": "listname",
      "recipient_count": 1
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
recipient_idReturned if recipient_id is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
recipient_idReturned if record for the recipient id does not exist

Get a Count of Billable Recipients [GET]

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients/billable_count HTTP/1.1

Response

1
2
3
4
HTTP/1.1 200
{
  "recipient_count": 2
}

Get a Count of Recipients [GET]

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients/count HTTP/1.1

Response

1
2
3
4
HTTP/1.1 200
{
  "recipient_count": 2
}

Search with conditions [POST]

Search using segment conditions without actually creating a segment. Body contains a JSON object with conditions, a list of conditions as described below, and an optional list_id, which is a valid list ID for a list to limit the search on.

Valid operators for create and update depend on the type of the field for which you are searching.

  • Dates:
    • "eq", "ne", "lt" (before), "gt" (after)
      • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
    • "empty", "not_empty"
    • "is within"
  • Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value), "empty", "not_empty"
  • Numbers: "eq", "lt", "gt", "empty", "not_empty"
  • Email Clicks and Opens: "eq" (opened), "ne" (not opened)

Field values must all be a string.

You can search for up to 15 different conditions per request.

Search conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either clicks.campaign_identifier or opens.campaign_identifier. The condition value should be a string containing the id of a completed campaign.

Search conditions list may contain multiple conditions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or".

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients/search HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "list_id": 4,
  "conditions": [
    {
      "field": "last_name",
      "value": "Miller",
      "operator": "eq",
      "and_or": ""
    },
    {
      "field": "birthday",
      "value": "P0Y1M1W3DT1H4M2S",
      "operator": "is within",
      "and_or": "and"
    },
    {
      "field": "date_joined",
      "value": "7",
      "operator": "is within",
      "and_or": "or"
    },
    {
      "field": "last_clicked",
      "value": "01/02/2015",
      "operator": "gt",
      "and_or": "and"
    },
    {
      "field": "clicks.campaign_identifier",
      "value": "513",
      "operator": "eq",
      "and_or": "or"
    }
  ]
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
HTTP/1.1 201
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "example@example.com",
      "first_name": null,
      "id": "YUBh",
      "last_clicked": 12345,
      "last_emailed": null,
      "last_name": "Miller",
      "last_opened": null,
      "updated_at": 1422313790,
      "custom_fields": [
        {
          "id": 23,
          "name": "pet",
          "value": "Fluffy",
          "type": "text"
        }
      ]
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
list_idReturned if the list_id does not exist or is invalid
and_orReturned if and_or and set value is not passed into the request body
and_orReturned if and_or is set on the only condition passed
and_orReturned if and_or is set on all conditions
and_orReturned if and_or is not set on more than one condition and less than all conditions
operatorReturned if operator and set value is not passed into the request body
valueReturned if value and set value is not passed into the request body
fieldReturned if field and set value is not passed into the request body
Returned if request body is not valid json
Returned if invalid value is passed into one of the request body parameters

Get Recipients Matching Search Criteria [GET]

"field_name" is a variable that is substituted for your actual custom field name from your recipient. This endpoint is similar to making a POST with conditions whose operator is "eq" and whose "and_or" values are "and". Text fields must be url-encoded. Date fields are searchable only by epoch with a granularity of day. For example, 1422835600 converts to Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through Mon, 02 Feb 2015 23:59:59 GMT.

URI Parameter Required Requirements Description
field_name Yes text The name of the field you're looking for

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients/search?{field_name}={value}&{field_name2}={value2} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
HTTP/1.1 200
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "example@example.com",
      "first_name": null,
      "id": "YUBh",
      "last_clicked": null,
      "last_emailed": null,
      "last_name": "Jones",
      "last_opened": null,
      "updated_at": 1422313790,
      "custom_fields": [
        {
          "id": 23,
          "name": "pet",
          "value": "Indiana",
          "type": "text"
        }
      ]
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
Returned if no search params are specified
fieldReturned if the provided field is invalid or does not exist
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
errorsReturned with message `No more pages` when at the end of the list

Segments

Body contains a JSON object with conditions, a list of conditions as described below, a unique name, and an optional list_id, which is a valid list ID for a list to limit the search on.

The JSON accepted by this endpoint is identical to that of the POST search with conditions, with the addition of requiring a unique name. (POST search with conditions is described above.)

Create a Segment [POST]

Request

1
POST https://api.sendgrid.com/v3/contactdb/segments HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "name": "Last Name Miller",
  "list_id": 4,
  "conditions": [
    {
      "field": "last_name",
      "value": "Miller",
      "operator": "eq",
      "and_or": ""
    },
    {
      "field": "last_clicked",
      "value": "01/02/2015",
      "operator": "gt",
      "and_or": "and"
    },
    {
      "field": "clicks.campaign_identifier",
      "value": "513",
      "operator": "eq",
      "and_or": "or"
    },
    {
      "field": "birthday",
      "value": "P2D1H",
      "operator": "is within",
      "and_or": "or"
    }
  ]
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
HTTP/1.1 201
{
  "id": 1,
  "name": "Last Name Miller",
  "list_id": 4,
  "conditions": [
    {
      "field": "last_name",
      "value": "Miller",
      "operator": "eq",
      "and_or": ""
    },
    {
      "field": "last_clicked",
      "value": "01/02/2015",
      "operator": "gt",
      "and_or": "and"
    },
    {
      "field": "clicks.campaign_identifier",
      "value": "513",
      "operator": "eq",
      "and_or": "or"
    }
  ],
  "recipient_count": 0
}

The response of the initial POST will return a recipient_count of 0 because it takes some time to populate. Follow up with a GET to verify segment size.

You can add up to 15 different conditions per segment.

1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
nameReturned if the name is not valid (it is not unique)
list_idReturned if the list_id is not valid
and_orReturned if and_or and set value is not passed into the request body
and_orReturned if and_or is set on the only condition passed
and_orReturned if and_or is set on all conditions
and_orReturned if and_or is not set on more than one condition and less than all conditions
operatorReturned if operator and set value is not passed into the request body
valueReturned if value and set value is not passed into the request body
fieldReturned if field and set value is not passed into the request body
Returned if request body is not valid json
Returned if invalid value is passed into one of the request body parameters

List All Segments [GET]

Request

1
GET https://api.sendgrid.com/v3/contactdb/segments HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
HTTP/1.1 200
{
  "segments": [
    {
      "id": 1,
      "name": "Last Name Miller",
      "list_id": 4,
      "conditions": [
        {
          "field": "last_name",
          "value": "Miller",
          "operator": "eq",
          "and_or": ""
        }
      ],
      "recipient_count": 1
    }
  ]
}

Retrieve a Segment [GET]

URI Parameter Required Requirements Description
segment_id Yes number The ID of the segment

Request

1
GET https://api.sendgrid.com/v3/contactdb/segments/{segment_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200
{
  "id": 1,
  "name": "Last Name Miller",
  "list_id": 4,
  "conditions": [
    {
      "field": "last_name",
      "value": "Miller",
      "operator": "eq",
      "and_or": ""
    }
  ],
  "recipient_count": 1
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
segment_idReturned if segment_id is not valid
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
segment_idReturned if segment_id does not exist
errorsReturned with message `No more pages` when at the end of the list

Update a Segment [PATCH]

URI Parameter Required Requirements Description
segment_id Yes number The ID of the segment

Request

1
PATCH https://api.sendgrid.com/v3/contactdb/segments/{segment_id} HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
{
  "name": "The Millers",
  "conditions": [
    {
      "field": "last_name",
      "value": "Miller",
      "operator": "eq",
      "and_or": ""
    }
  ]
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200
{
  "id": 5,
  "name": "The Millers",
  "list_id": 5,
  "conditions": [
    {
      "field": "last_name",
      "value": "Miller",
      "operator": "eq",
      "and_or": ""
    }
  ],
  "recipient_count": 1
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
segment_idReturned if segment_id is not valid
nameReturned if the name is not valid
list_idReturned if the list_id is not valid
and_orReturned if and_or and set value is not passed into the request body
and_orReturned if and_or is set on the only condition passed
and_orReturned if and_or is set on all conditions
and_orReturned if and_or is not set on more than one condition and less than all conditions
operatorReturned if operator and set value is not passed into the request body
valueReturned if value and set value is not passed into the request body
fieldReturned if field and set value is not passed into the request body
Returned if request body is not valid json
Returned if invalid value is passed into one of the request body parameters
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
segment_idReturned if segment_id does not exist

Delete a Segment [DELETE]

URI Parameter Required Requirements Description
delete_contacts No boolean True to delete all contacts matching the segment in addition to deleting the segment
Default: true

Request

1
DELETE https://api.sendgrid.com/v3/contactdb/segments/{segment_id} HTTP/1.1

Response

1
HTTP/1.1 204
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
segment_idReturned if segment_id is not valid
delete_contactsReturned if delete_contacts is not a valid boolean
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
segment_idReturned if segment_id does not exist

List Recipients On a Segment [GET]

URI Parameter Required Requirements Description
segment_id Yes number The ID of the segment
page_size No integer Number of recipients to return at a time (must be a positive integer from 1 to 1000)
Default: 100
page No integer Page index of recipients to return (must be a positive integer)
Default: 1

Request

1
GET https://api.sendgrid.com/v3/contactdb/segments/{segment_id}/recipients?page_size={page_size}&page={page} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
HTTP/1.1 200
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "example@example.com",
      "first_name": null,
      "id": "YUBh",
      "last_clicked": null,
      "last_emailed": null,
      "last_name": "Jones",
      "last_opened": null,
      "updated_at": 1422313790,
      "custom_fields": [
        {
          "id": 23,
          "name": "pet",
          "value": "Indiana",
          "type": "text"
        }
      ]
    }
  ]
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
pageReturned if page is not a valid integer
pageReturned if page is less than 1
page_sizeReturned if page_size is not a valid integer
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
segment_idReturned if segment_id is not valid
segment_idReturned if segment_id does not exist