Table of Contents

Emails

Add one or more emails to a Recipient List

Add an email recipient to a list

Legacy Newsletter

Request

1
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/add.json -F api_user=SENDGRID_USERNAME -F api_key=SENDGRID_PASSWORD -F 'list=my_list' -F 'data={"email":"example@example.com", "name":"Example User"}'

Response

1
2
3
{
  "inserted": 1
}

Marketing Campaigns

To insert a recipient into a list, you need the list id and the recipient id.

First, we get the list id:

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/lists \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
6
7
8
9
{
  "lists": [
    {
      "id": 1,
      "name": "my_list",
      "recipient_count": 1
    }
  ]
}

Then, we get the recipient id (alternatively, you can get the recipient id by base64 encoding the email address):

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/recipients \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "jones@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"
        }
      ]
    }
  ]
}

Now we can add the recipient to the desired list:

Request

1
2
3
4
5
curl --request POST \
--url https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients/{recipient_id} \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Request

1
HTTP/1.1 201

Add an email recipient with multiple data fields

Legacy Newsletter

Request

1
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/add.json -F api_user=SENDGRID_USERNAME -F api_key=SENDGRID_PASSWORD -F 'list=my_list' -F 'data={"email":"example@example.com", "name":"Example User", "city":"Denver", "country":"USA"}'

Response

1
2
3
{
  "inserted": 1
}

Marketing Campaigns

First, we get the list id:

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/lists \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
6
7
8
9
{
  "lists": [
    {
      "id": 1,
      "name": "my_list",
      "recipient_count": 1
    }
  ]
}

Then, we get the recipient id (alternatively, you can get the recipient id by base64 encoding the email address):

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/recipients \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "jones@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"
        }
      ]
    }
  ]
}

Now we can add the recipient to the desired list:

Request

1
2
3
4
5
curl --request POST \
--url https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients/{recipient_id} \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
HTTP/1.1 201

Add multiple email recipients to a list

Legacy Newsletter

Request

1
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/add.json -F api_user=SENDGRID_USERNAME -F api_key=SENDGRID_PASSWORD -F 'list=my_list' -F 'data[]={"email":"example@example.com", "name":"Example User"}' -F 'data[]={"email":"example2@example.com", "name":"Example User2"}'

Response

1
2
3
{
  "inserted": 2
}

Marketing Campaigns

First, we get the list id:

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/lists \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
6
7
8
9
{
  "lists": [
    {
      "id": 1,
      "name": "my_list",
      "recipient_count": 1
    }
  ]
}

Then, we get the recipient id (alternatively, you can get the recipient id by base64 encoding the email address):

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/recipients \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

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
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "jones@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"
        }
      ]
    },
    {
      "created_at": 1432313607,
      "email": "jones2@example.com",
      "first_name": null,
      "id": "YUBhx",
      "last_clicked": null,
      "last_emailed": null,
      "last_name": "Jonesy",
      "last_opened": null,
      "updated_at": 1423313790,
      "custom_fields": [
        {
          "id": 23,
          "name": "pet",
          "value": "Indiana",
          "type": "text"
        }
      ]
    }
  ]
}

Now we can add the recipient to the desired list.

Request

1
2
3
4
5
6
curl --request POST \
--url https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json' \
--data '["YUBh","YUBhx"]'

Response

1
HTTP/1.1 201

Get the email addresses and associated fields for a Recipient List

Legacy Newsletter

Request

1
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/get.json -F api_user=SENDGRID_USERNAME -F api_key=SENDGRID_PASSWORD -F 'list=my_list'

Response

1
2
3
4
5
6
[
  {
    "email": "example@example.com",
    "name": "Example User"
  }
]

Marketing Campaigns

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "recipients": [
    {
      "created_at": 1422395108,
      "email": "example@example.com",
      "first_name": "Example User",
      "id": "YUBh",
      "last_clicked": null,
      "last_emailed": null,
      "last_name": null,
      "last_opened": null,
      "updated_at": 1422395108
    }
  ]
}

Retrieve the number of entries on a Recipient List

Legacy Newsletter

Request

1
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/count.json -F api_user=SENDGRID_USERNAME -F api_key=SENDGRID_PASSWORD -F 'list=my_list'

Response

1
2
3
{
  "count": 1
}

Marketing Campaigns

First, we need to get the list_id:

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/lists \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

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

Now we can retrieve the number of entries in the list:

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/lists/{list_id} \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
{
  "id": 1,
  "name": "my_list",
  "recipient_count": 1
}

Remove one or more emails from a Recipient List

Legacy Newsletter

Request

1
curl -X POST https://api.sendgrid.com/api/newsletter/lists/email/delete.json -F api_user=SENDGRID_USERNAME -F api_key=SENDGRID_PASSWORD -F 'list=my_list' -F email[]=example@example.com

Response

1
2
3
{
  "removed": 1
}

Marketing Campaigns

First, we get the list id:

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/lists \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
2
3
4
5
6
7
8
9
{
  "lists": [
    {
      "id": 1,
      "name": "my_list",
      "recipient_count": 1
    }
  ]
}

Then, we get the recipient id (alternatively, you can get the recipient id by base64 encoding the email address):

Request

1
2
3
4
5
curl --request GET \
--url https://api.sendgrid.com/v3/contactdb/recipients \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

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
{
  "recipients": [
    {
      "created_at": 1422313607,
      "email": "jones@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"
        }
      ]
    },
    {
      "created_at": 1432313607,
      "email": "jones2@example.com",
      "first_name": null,
      "id": "YUBhx",
      "last_clicked": null,
      "last_emailed": null,
      "last_name": "Jonesy",
      "last_opened": null,
      "updated_at": 1423313790,
      "custom_fields": [
        {
          "id": 23,
          "name": "pet",
          "value": "Indiana",
          "type": "text"
        }
      ]
    }
  ]
}

Now we can delete the recipient to the desired list:

Request

1
2
3
4
5
curl --request DELETE \
--url https://api.sendgrid.com/v3/contactdb/lists/{list_id}/recipients/{recipient_id} \
--header 'accept: application/json' \
--header 'authorization: Bearer SENDGRID_API_KEY' \
--header 'content-type: application/json'

Response

1
HTTP/1.1 204