Campaigns API

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

Campaigns

Marketing Campaigns API

Marketing Campaign APIを使用することでキャンペーンの作成、管理、送信、スケジュール指定を行うことができます。

Campaigns

CampaignsはMarketing Campaigns APIの関連リソースです。

Campaignを作成するにはtitleが必要となります。 Campaignを送信もしくはスケジュール指定するには、subject、sender_id、コンテンツ(html_content、plain_conetnt)、そしてlist_idsもしくはsegment_idsいずれかが必要となります。

HTMLパートおよびテキストパートに [unsubscribe] タグを含める必要があります。

Create a Campaign [POST]

Campaignの作成

Request

1

POST https://api.sendgrid.com/v3/campaigns 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

{
  "title": "March Newsletter",
  "subject": "New Products for Spring!",
  "sender_id": 124451,
  "list_ids": [
    110,
    124
  ],
  "segment_ids": [
    110
  ],
  "categories": [
    "spring line"
  ],
  "suppression_group_id": 42,
  "custom_unsubscribe_url": "",
  "ip_pool": "marketing",
  "html_content": "<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>",
  "plain_content": "Check out our spring line!"
}

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
{
  "id": 986724,
  "title": "March Newsletter",
  "subject": "New Products for Spring!",
  "sender_id": 124451,
  "list_ids": [
    110,
    124
  ],
  "segment_ids": [
    110
  ],
  "categories": [
    "spring line"
  ],
  "suppression_group_id": 42,
  "custom_unsubscribe_url": "",
  "ip_pool": "marketing",
  "html_content": "<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>",
  "plain_content": "Check out our spring line!",
  "status": "Draft",
  "editor": "code"
}

1

HTTP/1.1 400

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

フィールド エラーメッセージ
titletitle can't be blank：titleは空にすることができません
titletitle is too long (maximum is 100 characters)：タイトルが長過ぎます（最大100文字）
categoriescategories exceeds 10 category limit：カテゴリが10の制限を超えました
html_contenthtml_content exceeds the 1MB limit：html_contentが1MBの制限を超えました
plain_contentplain_content exceeds the 1MB limit：plain_contentが1MBの制限を超えました
sender_idsender_id does not exist：sender_idが存在しません
sender_idsender_id is not a verified sender identity：sender_idが確認されていません
list_idslist_ids do not all exist：list_idsが全て存在しません
segment_idssegment_ids do not all exist：segment_idsが全て存在しません
ip_poolThe ip pool you provided is invalid：IPが不正です
suppression_group_idsuppression_group_id does not exist：suppresison_group_idが存在しません
editoreditor must be 'code' or 'design' if included. If not included, 'code' will be selected by default.：'code'または'design'を指定してください。指定されていない場合、'code'がデフォルト値として選択されます。
unsubscribesEither suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.：suppression_group_idまたはcustom_unsubscribe_urlのいずれかを設定または使用できますが、両方を使用することはできません。一方かを設定する前に削除してください。
The JSON you have submitted cannot be parsed.：指定されたJSONをパースすることができませんでした
You've reached your limit of 2500 campaigns. Please delete one or more and try again.：キャンペーン数が上限の2500に達しました。削除後再度試してください。

Get all Campaigns [GET]

作成順と逆順でキャンペーンの一覧を取得します（新しいものが最初に取得されます） キャンペーンを作成していない場合空のリストが返ります。
URI引数 必須 条件 説明
limit No number 取得するキャンペーンの最大数
Default: 10
offset No number 最初に取得するキャンペーンのインデクス。0は最初のキャンペーン
Default: 0

Request

1

GET https://api.sendgrid.com/v3/campaigns?limit={limit}&offset={offset} 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
50
51

HTTP/1.1 200
{
  "result": [
    {
      "id": 986724,
      "title": "March Newsletter",
      "subject": "New Products for Spring!",
      "sender_id": 124451,
      "list_ids": [
        110,
        124
      ],
      "segment_ids": [
        110
      ],
      "categories": [
        "spring line"
      ],
      "suppression_group_id": 42,
      "custom_unsubscribe_url": "",
      "ip_pool": "marketing",
      "html_content": "<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>",
      "plain_content": "Check out our spring line!",
      "editor": "design",
      "status": "Draft"
    },
    {
      "id": 986723,
      "title": "February Newsletter",
      "subject": "Final Winter Product Sale!",
      "sender_id": 124451,
      "list_ids": [
        110,
        124
      ],
      "segment_ids": [
        110
      ],
      "categories": [
        "winter line"
      ],
      "suppression_group_id": 42,
      "custom_unsubscribe_url": "",
      "ip_pool": "marketing",
      "html_content": "<html><head><title></title></head><body><p>Last call for winter clothes!</p></body></html>",
      "plain_content": "Last call for winter clothes!",
      "editor": "design",
      "status": "Sent"
    }
  ]
}

View a Campaign [GET]

キャンペーンの閲覧
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

GET https://api.sendgrid.com/v3/campaigns/{campaign_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
21
22
23

HTTP/1.1 200
{
  "id": 986724,
  "title": "March Newsletter",
  "subject": "New Products for Spring!",
  "sender_id": 124451,
  "list_ids": [
    110,
    124
  ],
  "segment_ids": [
    110
  ],
  "categories": [
    "spring line"
  ],
  "suppression_group_id": 42,
  "custom_unsubscribe_url": "",
  "ip_pool": "marketing",
  "html_content": "<html><head><title></title></head><body><p>Check out our spring line!</p></body></html>",
  "plain_content": "Check out our spring line!",
  "status": "Draft"
}

1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません

Delete a Campaign [DELETE]

キャンペーンの削除
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

DELETE https://api.sendgrid.com/v3/campaigns/{campaign_id} HTTP/1.1

Response

1

HTTP/1.1 204

1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません

Update a Campaign [PATCH]

キャンペーンの更新
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

PATCH https://api.sendgrid.com/v3/campaigns/{campaign_id} HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9

{
  "title": "May Newsletter",
  "subject": "New Products for Summer!",
  "categories": [
    "summer line"
  ],
  "html_content": "<html><head><title></title></head><body><p>Check out our summer line!</p></body></html>",
  "plain_content": "Check out our summer line!"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

HTTP/1.1 200
{
  "id": 986724,
  "title": "May Newsletter",
  "subject": "New Products for Summer!",
  "sender_id": 124451,
  "list_ids": [
    110,
    124
  ],
  "segment_ids": [
    110
  ],
  "categories": [
    "summer line"
  ],
  "suppression_group_id": 42,
  "custom_unsubscribe_url": "",
  "ip_pool": "marketing",
  "html_content": "<html><head><title></title></head><body><p>Check out our summer line!</p></body></html>",
  "plain_content": "Check out our summer line!",
  "status": "Draft"
}

1

HTTP/1.1 400

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

フィールド エラーメッセージ
titletitle can't be blank：titleは空にすることができません
titletitle is too long (maximum is 100 characters)：タイトルが長過ぎます（最大100文字）
categoriescategories exceeds 10 category limit：カテゴリが10の制限を超えました
html_contenthtml_content exceeds the 1MB limit：html_contentが1MBの制限を超えました
plain_contentplain_content exceeds the 1MB limit：plain_contentが1MBの制限を超えました
sender_idsender_id does not exist：sender_idが存在しません
sender_idsender_id is not a verified sender identity：sender_idが確認されていません
list_idslist_ids do not all exist：list_idsが全て存在しません
segment_idssegment_ids do not all exist：segment_idsが全て存在しません
ip_poolThe ip pool you provided is invalid：IPが不正です
suppression_group_idsuppression_group_id does not exist：suppresison_group_idが存在しません
editorYou cannot switch editors once a campaign has been created.：一度キャンペーンを作成するとエディタを変更することはできません
unsubscribesEither suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.：suppression_group_idまたはcustom_unsubscribe_urlのいずれかを設定または使用できますが、両方を使用することはできません。一方かを設定する前に削除してください。
The JSON you have submitted cannot be parsed.：指定されたJSONをパースすることができませんでした
1

HTTP/1.1 403

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

フィールド エラーメッセージ
You may only update a campaign when it is in draft mode.：ドラフトモードの場合のみキャンペーンを更新できます
1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません

Send a Campaign [POST]

キャンペーンの送信
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

POST https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules/now HTTP/1.1

Response

1
2
3
4
5

HTTP/1.1 201
{
  "id": 986724,
  "status": "Scheduled"
}

1

HTTP/1.1 400

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

フィールド エラーメッセージ
subjectsubject can't be blank：subjectは空にすることができません
sender_idsender_id can't be blank：sender_idは空にすることができません
plain_contentplain_content can't be blank, please provide plain text or html content：plain_contentは空にすることができません。plain textもしくはhtml contentを指定してください
list_idsYou must select at least 1 segment or 1 list to send to.：セグメントもしくはリストを最低1つ指定する必要があります
unsubscribe_tagAn [unsubscribe] tag in both your html and plain content is required to send a campaign.：キャンペーンを送信するには[unsubscribe]タグをhtmlおよびplain contentに含める必要があります
suppression_group_idEither a suppression_group_id or custom_unsubscribe_url is required to send a campaign.：キャンペーンを送信するにはsuppression_group_idまたはcustom_unsubscribe_urlを指定する必要があります
You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing：このキャンペーンを送信するための十分なクレジットがありません。プランのアップグレードをご検討ください
1

HTTP/1.1 403

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

フィールド エラーメッセージ
You may only send a campaign when it is in draft mode.：ドラフトモードの場合のみキャンペーンを更新できます
1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません
1

HTTP/1.1 500

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

フィールド エラーメッセージ
Failed to send your campaign.：キャンペーンの送信に失敗しました

Schedule a Campaign [POST]

キャンペーンのスケジュール
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

POST https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules HTTP/1.1
Request Body
1
2
3

{
  "send_at": 1489771528
}

Response

1
2
3
4
5
6

HTTP/1.1 200
{
  "id": 986724,
  "send_at": 1489771528,
  "status": "Scheduled"
}

1

HTTP/1.1 400

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

フィールド エラーメッセージ
subjectsubject can't be blank：subjectは空にすることができません
sender_idsender_id can't be blank：sender_idは空にすることができません
plain_contentplain_content can't be blank, please provide plain text or html content：plain_contentは空にすることができません。plain textもしくはhtml contentを指定してください
list_idsYou must select at least 1 segment or 1 list to send to.：セグメントもしくはリストを最低1つ指定する必要があります
send_atPlease choose a future time for sending your campaign.：キャンペーンを送信するには未来の時刻を指定してください
unsubscribe_tagAn [unsubscribe] tag in both your html and plain content is required to send a campaign.：キャンペーンを送信するには[unsubscribe]タグをhtmlおよびplain contentに含める必要があります
suppression_group_idEither a suppression_group_id or custom_unsubscribe_url is required to send a campaign.：キャンペーンを送信するにはsuppression_group_idまたはcustom_unsubscribe_urlを指定する必要があります
The JSON you have submitted cannot be parsed.：指定されたJSONをパースすることができませんでした
You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing：このキャンペーンを送信するための十分なクレジットがありません。プランのアップグレードをご検討ください
1

HTTP/1.1 403

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

フィールド エラーメッセージ
You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.：すでに送信済みもしくはスケジュール済みのためPOSTできませんでした。スケジュールされたキャンペーンを更新する場合PATCHを利用してください
1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりませんでした

Update a Scheduled Campaign [PATCH]

スケジュールされたキャンペーンの更新。指定したキャンペーンのsend_atを変更します。
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

PATCH https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules HTTP/1.1
Request Body
1
2
3

{
  "send_at": 1489451436
}

Response

1
2
3
4
5
6

HTTP/1.1 200
{
  "id": 986724,
  "send_at": 1489451436,
  "status": "Scheduled"
}

1

HTTP/1.1 400

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

フィールド エラーメッセージ
The JSON you have submitted cannot be parsed.：指定されたJSONをパースすることができませんでした
send_atPlease choose a future time for sending your campaign.：キャンペーンを送信するには未来の時刻を指定してください
You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing：このキャンペーンを送信するための十分なクレジットがありません。プランのアップグレードをご検討ください
1

HTTP/1.1 403

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

フィールド エラーメッセージ
send_atYou cannot update the send_at value of non-scheduled campaign.：スケジュール指定されていないキャンペーンはsend_atの値を更新できません
1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません

View Scheduled Time of a Campaign [GET]

キャンペーンのスケジュール時刻の確認
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

GET https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules HTTP/1.1

Response

1
2
3
4

HTTP/1.1 200
{
  "send_at": 1489771528
}

1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません

Unschedule a Scheduled Campaign [DELETE]

スケジュールされたキャンペーンのスケジュール指定の解除。 スケジュールのキャンセルに成功すると204を返します。 指定したキャンペーンが送信処理中の場合、キャンセルのみ可能です（別メソッドです）
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

DELETE https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules HTTP/1.1

Response

1

HTTP/1.1 204

1

HTTP/1.1 403

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

フィールド エラーメッセージ
This campaign is already In Progress.：このキャンペーンは送信処理中です
This campaign is already Sent.：このキャンペーンは送信済みです
This campaign is already Paused.：このキャンペーンは一時停止されています
This campaign is already Canceled.：このキャンペーンはキャンセルされています
1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません

Send a Test Campaign [POST]

キャンペーンのテスト送信。複数のアドレスに送信する場合、JSONの"to"の値に配列を指定してください　["one@address","two@address"]
URI引数 必須 条件 説明
campaign_id Yes number キャンペーンID

Request

1

POST https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules/test HTTP/1.1
Request Body
1
2
3

{
  "to": "example@example.com"
}

Response

1

HTTP/1.1 204

1

HTTP/1.1 400

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

フィールド エラーメッセージ
The JSON you have submitted cannot be parsed.：指定されたJSONをパースすることができませんでした
toPlease provide an email address to which the test should be sent.：テスト送信するためのメールアドレスを指定してください
toYou can only send tests to 10 addresses at a time.：テスト送信できるアドレスの上限は一度に10アドレスまでです
subjectPlease add a subject to your campaign before sending a test.：テスト送信前にキャンペーンにsubjectを設定してください
plain_contentPlain content and html content can't both be blank. Please set one of these values before sending a test.：plain contentとhtml content両方を空にすることはできません。テスト送信前にこれらどちらかに値を設定してください
sender_idPlease assign a sender identity to your campaign before sending a test.：テスト送信前にキャンペーンに送信者を割り当ててください
1

HTTP/1.1 404

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

フィールド エラーメッセージ
not found：見つかりません