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:見つかりません