Contacts API

本エンドポイントの利用方法と認証の詳細についてはAPI Keyページを参照してください。

Custom Fields Lists Recipients Segments

Contacts API

宛先IDは不透明なものとして扱ってください。Recipientエンドポイントが返すidは宛先IDを必要とするエンドポイントにそのまま渡してください。

宛先IDはメールアドレスをBase64形式でエンコードした値として生成されます。宛先IDからメールアドレスへの変換（もしくはその逆）は、例えばhttps://www.base64encode.org/のようなBase64エンコーダ/デコーダが利用できます。

いくつかの呼び出しで利用可能な page_size パラメータは曖昧な値です。データストアの仕組み上、指定した値と多少異なる数のデータを受信することがあります。

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
リクエストボディのJSONが不正な場合に返されます
typeカスタムフィールドのtypeが不正な場合または指定されていない場合に返されます
nameカスタムフィールドのnameが指定されていない場合に返されます
作成可能なカスタムフィールド数の上限は120です。

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引数 必須 条件 説明
custom_field_id Yes number カスタムフィールドのID

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

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
custom_field_idcustom_field_idが存在しない場合に返されます

Delete a Custom Field [DELETE]

カスタムフィールドの削除
URI引数 必須 条件 説明
custom_field_id Yes number カスタムフィールドのID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
idcustom_field_idが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
custom_field_idcustom_field_idが存在しない場合に返されます

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

宛先IDはURLセーフで、宛先のメールアドレスをすべて小文字にしたものをBase64エンコードしたものです。例えば、メールアドレスがfoo@example.comの宛先IDは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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
name既存のリストまたはセグメントとnameが重複している場合に返されます
nameリストのnameが文字列ではない場合に返されます
リクエストボディのJSONが不正な場合に返されます

List All Lists [GET]

リストの一覧取得。リスト未作成の場合は空のリストが返ります。

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
idすべてのリストIDが不正な場合に返されます

Retrieve a List [GET]

リストの取得
URI引数 必須 条件 説明
list_id Yes number リストID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが存在しない場合に返されます

Update a List [PATCH]

リストの更新
URI引数 必須 条件 説明
list_id Yes number リストID

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引数 必須 条件 説明
list_id Yes number リストID

Request

1

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

Response

1

HTTP/1.1 400
URI引数 必須 条件 説明
list_id Yes number リストID

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引数 必須 条件 説明
delete_contacts No boolean リストを削除すると共にリスト内のすべての宛先を削除する場合trueを指定します
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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが不正な場合に返されます
delete_contactsdelete_contactsが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが存在しなかった場合に返されます

List Recipients on a List [GET]

リスト内の宛先リストの取得
URI引数 必須 条件 説明
list_id Yes integer リストID
page No integer 取得する宛先の最初のページのインデクス（正の整数）
Default: 1
page_size No integer 一度に取得する宛先数 (1〜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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが不正な場合に返されます
pagepageが不正な場合に返されます
pagepageが1より小さい場合に返されます
page_sizepage_sizeが不正な場合に返されます
page_sizepage_sizeが1より小さいまたは1000より大きい場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが存在しない場合に返されます

Add a Single Recipient to a List [POST]

リストへの宛先の追加

個々の宛先をリストに追加する際、1秒間に1000リクエストが上限です。ここでは、1回のリクエストあたり、ひとつの宛先がリストに追加されます。

URI引数 必須 条件 説明
list_id Yes number リストID
recipient_id Yes string 宛先ID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが不正な場合に返されます
recipient_idrecipient_idが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが存在しない場合に返されます
recipient_idrecipient_idが存在しない場合に返されます

Delete a Single Recipient from a Single List [DELETE]

リストからの宛先の削除
URI引数 必須 条件 説明
list_id Yes number リストID
recipient_id Yes string 宛先ID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが不正な場合に返されます
recipient_idrecipient_idが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが存在しない場合に返されます
recipient_idrecipient_idが存在しない場合に返されます

Add Multiple Recipients to a List [POST]

リストへの複数宛先の追加

宛先IDを指定して既存の宛先をリストに追加します。宛先IDはRecipientエンドポイントから返されたものを正確に指定する必要があります。

リストへの宛先の追加は1秒間に1回までに制限されています。指定可能な宛先数は1回のリクエストあたり1000が上限です。

URI引数 必須 条件 説明
list_id Yes number リストID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが不正な場合に返されます
正常な宛先IDが指定されなかった場合に返されます
宛先が追加されなかった場合に返されます
リクエストボディのJSONが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが存在しない場合に返されます
errorsリストの最後まで表示していた場合 `No more pages` のメッセージが返されます

Recipients

重複した宛先をアップロードしたり、元の宛先に変更のない要求を送信した場合、元の宛先は変更されず、そのindexがunmodified_indicesリストに追加されます。

Add Single Recipient [POST]

単一の宛先の追加

宛先の追加リクエストは2秒毎に3回に制限されています。指定可能な宛先数は1回のリクエストあたり1000が上限です。この結果、1秒間に最大1500宛先までアップロード可能です。

Request

1

POST https://api.sendgrid.com/v3/contactdb/recipients HTTP/1.1
Request Body
1
2
3
4
5
6
7
8

[
  {
    "email": "eexampexample@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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
リクエストボディの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": "eexampexample@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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
リクエストボディのJSONが不正な場合に返されます

Update Recipient [PATCH]

宛先の更新。ボディには宛先オブジェクトのリストを指定します。

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
リクエストボディのJSONが不正な場合に返されます

Delete Recipient [DELETE]

宛先の削除。ボディには削除する宛先IDのリストを指定します。

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
削除される宛先がなかった場合に返されます
指定された宛先IDが不正な場合に返されます
リクエストボディのJSONが不正な場合に返されます

バッチ削除を行うことにより空のページが返される場合があります。これを避けるために、404が返されるまでページを取得してください。

List Recipients [GET]

宛先の一覧取得
URI引数 必須 条件 説明
page No integer 最初の宛先のページインデクス（正の整数）
Default: 1
page_size No integer 一度に取得する宛先数 (1〜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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
pagepageが不正な場合に返されます
pagepageが1より小さい場合に返されます
page_sizepage_sizeが不正な場合に返されます
page_sizepage_sizeが1より小さいまたは1000より大きい場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
errorsリストの最後まで表示していた場合 `No more pages` のメッセージが返されます

Retrieve a Recipient [GET]

宛先の取得
URI引数 必須 条件 説明
recipient_id Yes number 宛先ID

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": "Fluffy",
      "type": "text"
    }
  ]
}

1

HTTP/1.1 400

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
recipient_idrecipient_idが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
recipient_idrecipient_idが存在しない場合に返されます

Delete a Recipient [DELETE]

宛先の削除
URI引数 必須 条件 説明
recipient_id Yes number 宛先ID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
recipient_idrecipient_idが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
recipient_idrecipient_idが存在しない場合に返されます

Get the Lists the Recipient Is On [GET]

宛先が含まれるリストの取得
URI引数 必須 条件 説明
recipient_id Yes string 宛先ID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
recipient_idrecipient_idが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
recipient_idrecipient_idが存在しない場合に返されます

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]

条件付き検索

セグメントの条件によリ検索を行います。 ボディにはconditionsを伴ったJSONオブジェクト、以下で説明する条件のリスト、およびlist_id（任意、検索対象のリストを指定するリストIDのリスト）を含めます。

検索対象のフィールドの型に応じた適切な演算子。

  • Dates:
    • "eq", "ne", "lt" (before), "gt" (after)
      • 日にち単位で指定する場合、MM/DD/YYYY形式を利用できます。秒単位で指定する場合、UNIXタイムが利用できます。
    • "empty", "not_empty"
    • "is within"
  • Text: "contains", "eq" (is - 完全一致), "ne" (is not - 一致しない), "empty", "not_empty"
  • Numbers: "eq", "lt", "gt", "empty", "not_empty"
  • Email Clicks and Opens: "eq" (開封された), "ne" (開封されていない)

フィールドの値は全て文字列である必要があります。

1リクエストあたり最大15条件まで検索可能です。

メールのクリックと開封のセグメント条件"eq"もしくは"ne"はclicks.campaign_identifierおよびopens.campaign_identifierの両方を"field"に指定する必要があります。 条件には完了したキャンペーンのIDを含む文字列を指定してください。

セグメントは複数の条件を含む場合があり、"and_or"フィールドの"and"または"or"で結合されます。 最初の条件は"and_or"が空の状態で、それ以降の条件は"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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
list_idlist_idが存在しないまたは不正な場合に返されます
and_orand_orと値がリクエストボディに指定されなかった場合に返されます
and_orand_orが一つの条件にのみ指定された場合に返されます
and_orすべての条件に対してand_orが指定された場合に返されます
and_orひとつ以上の条件に対してand_orが指定されなかった、かつ全てではない条件に対してand_orが指定されなかった場合に返されます
operatorリクエストボディにoperatorとvalueが指定されなかった場合に返されます
valueリクエストボディにvalueが指定されなかった場合に返されます
fieldリクエストボディにfieldとvalueが指定されなかった場合に返されます
リクエストボディのJSONが不正な場合に返されます
リクエストボディのパラメータの一つが不正な場合に返されます

Get Recipients Matching Search Criteria [GET]

検索条件にマッチする宛先の取得

"field_name"は宛先が持っている実際のカスタムフィールド名に置換される変数です。 このエンドポイントは「Search with conditions [POST]」で演算子"eq"、"and_or"の値を"and"とした場合の動作と似ています。 テキストフィールドはURLエンコードされる必要があります。 DateフィールドはUNIXタイムスタンプでのみ検索可能です。 例えば、1422835600 は Mon, 02 Feb 2015 00:06:40 GMT に変換されますが、内部的にはシステムは Mon, 02 Feb 2015 00:00:00 GMT から Mon, 02 Feb 2015 23:59:59 GMTを検索します。

URI引数 必須 条件 説明
field_name Yes text 検索対象のフィールド名

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": "Fluffy",
          "type": "text"
        }
      ]
    }
  ]
}

1

HTTP/1.1 400

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
検索パラメータが指定されなかった場合に返されます
field指定されたフィールドが不正もしくは存在しなかった場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
errorsリストの最後まで表示していた場合 `No more pages` のメッセージが返されます

Segments

ボディにはconditionsを伴ったJSONオブジェクト、以下で説明する条件のリスト、およびlist_id（任意、検索対象のリストを指定するリストIDのリスト）を含めます。

このエンドポイントで受け付けられたJSONは、search with conditions [POST]と同じですが、ユニークな名前が必要になります。（「Search with conditions [POST]」については上記で説明しています。）

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
}

反映に時間がかかるため、POST実行後のrecipient_countは0を返します。セグメントサイズの確認にはGETを利用してください。

1セグメントあたり指定可能な条件の最大数は15です。

1

HTTP/1.1 400

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
namenameが不正な場合に返されます（ユニークではない場合など）
list_idlist_idが不正な場合に返されます
and_orand_orと値がリクエストボディに指定されなかった場合に返されます
and_orand_orが一つの条件にのみ指定された場合に返されます
and_orすべての条件に対してand_orが指定された場合に返されます
and_orひとつ以上の条件に対してand_orが指定されなかった、かつ全てではない条件に対してand_orが指定されなかった場合に返されます
operatorリクエストボディにoperatorとvalueが指定されなかった場合に返されます
valueリクエストボディにvalueが指定されなかった場合に返されます
fieldリクエストボディにfieldとvalueが指定されなかった場合に返されます
リクエストボディのJSONが不正な場合に返されます
リクエストボディのパラメータの一つが不正な場合に返されます

List All Segments [GET]

セグメントの一覧取得
URI引数 必須 条件 説明
exclude No string セグメントの recipient_count 更新された値が不要な場合、この引数を追加してください。これにより、クエリの応答速度が速くなります.
Default: "count"

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引数 必須 条件 説明
segment_id Yes number セグメントID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
segment_idsegment_idが指定されなかった場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
segment_idsegment_idが存在しなかった場合に返されます
errorsリストの最後まで表示していた場合 `No more pages` のメッセージが返されます

Update a Segment [PATCH]

セグメントの更新
URI引数 必須 条件 説明
segment_id Yes number セグメントID

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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
segment_idsegment_idが不正な場合に返されます
namenameが不正な場合に返されます
list_idlist_idが不正な場合に返されます
and_orand_orと値がリクエストボディに指定されなかった場合に返されます
and_orand_orが一つの条件にのみ指定された場合に返されます
and_orすべての条件に対してand_orが指定された場合に返されます
and_orひとつ以上の条件に対してand_orが指定されなかった、かつ全てではない条件に対してand_orが指定されなかった場合に返されます
operatorリクエストボディにoperatorとvalueが指定されなかった場合に返されます
valueリクエストボディにvalueが指定されなかった場合に返されます
fieldリクエストボディにfieldとvalueが指定されなかった場合に返されます
リクエストボディのJSONが不正な場合に返されます
リクエストボディのパラメータの一つが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
segment_idsegment_idが存在しなかった場合に返されます

Delete a Segment [DELETE]

セグメントの削除
URI引数 必須 条件 説明
delete_contacts No boolean セグメントの削除と一緒にセグメント内のすべての宛先を削除する場合trueを指定します
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

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
segment_idsegment_idが不正な場合に返されます
delete_contactsdelete_contactsがbooleanでない場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
segment_idsegment_idが存在しなかった場合に返されます

List Recipients On a Segment [GET]

セグメント内の宛先リストの取得
URI引数 必須 条件 説明
segment_id Yes number セグメントID
page_size No integer 一度に取得する宛先数 (1〜1000の間の整数)
Default: 100
page No 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": "Fluffy",
          "type": "text"
        }
      ]
    }
  ]
}

1

HTTP/1.1 400

発生しうる 400 エラーメッセージ

フィールド エラーメッセージ
pagepageが不正な場合に返されます
pagepageが1より小さい場合に返されます
page_sizepage_sizeが不正な場合に返されます
1

HTTP/1.1 404

発生しうる 404 エラーメッセージ

フィールド エラーメッセージ
segment_idsegment_idが不正な場合に返されます
segment_idsegment_idが存在しない場合に返されます