Contacts API

Marketing Emails機能からマイグレーションを行う場合、こちらを参照してください。

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

Custom Fields Lists Recipients Segments

Contacts API

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

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が指定されていない場合に返されます

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
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"
    }
  ]
}

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": "e@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": "jones@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": "jones@example.com",
    "last_name": "Jones",
    "pet": "Fluffy",
    "age": 25
  },
  {
    "email": "miller@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": "jones@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": "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"
        }
      ]
    }
  ]
}
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": "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": "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]

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

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

  • Dates: "eq", "ne", "lt" (before), "gt" (after)
  • Text: "contains", "eq" (is - 完全一致), "ne" (is not - 一致しない)
  • Numbers: "eq", "lt", "gt"
  • メールのクリックと開封: "eq" (opened), "ne" (not opened)

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

セグメントは複数の条件を含む場合があり、"and_or"フィールドの"and"または"or"で結合されます。最初の条件は"and_or"が空の状態で、それ以降の条件は"and_or"を指定する必要があります。

Request

1
POST 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
{
  "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"
    }
  ]
}

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": "jones@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が不正な場合に返されます
リクエストボディのパラメータの一つが不正な場合に返されます

“field_name”は宛先が持っている実際のカスタムフィールド名に置換される変数です。 テキストフィールドはURLエンコードされる必要があります。DateフィールドはUNIXタイムスタンプでのみ検索可能です(例えば、2/2/2015は1422835200となります)。

field_nameが予約フィールドの場合、create_atもしくはupdated_atのように、システムは内部的に当日の日付範囲に含まれるよう内部的に日付を変換します。 例えば、1422835600はMon, 02 Feb 2015 00:06:40 GMTですが、システムは内部的に02 Feb 2015 00:00:00 GMTからMon, 02 Feb 2015 23:59:59 GMTに変換します。

Get Recipients Matching Search Criteria [GET]

検索条件にマッチする宛先の取得
URI引数 必須 条件 説明
field_name Yes text 検索対象のフィールド名

Request

1
GET https://api.sendgrid.com/v3/contactdb/recipients/search?{field_name}={value} 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": "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": "Fluffy",
          "type": "text"
        }
      ]
    }
  ]
}
1
HTTP/1.1 400

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

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

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

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

Segments

作成および更新時に使用される適切な演算子はセグメント対象のフィールドのタイプに依存します。
  • Dates: "eq", "ne", "lt" (before), "gt" (after)
  • Text: "contains", "eq" (is - 完全一致), "ne" (is not - 一致しない)
  • Numbers: "eq", "lt", "gt"
  • メールのクリックと開封: "eq" (opened), "ne" (not opened)
メールのクリックと開封のセグメント条件"eq"もしくは"ne"はclicks.ampaign_identifierおよびopens.campaign_identifierの両方を"field"に指定する必要があります。条件には完了したキャンペーンのIDを含む文字列を指定してください。セグメントは複数の条件を含む場合があり、"and_or"フィールドの"and"または"or"で結合されます。最初の条件は"and_or"が空の状態で、それ以降の条件は"and_or"を指定する必要があります。

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
{
  "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"
    }
  ]
}

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
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]

セグメントの一覧取得

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": "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": "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が存在しない場合に返されます