Please refer to our API Key page for information on how to authenticate and use these endpoints.

Campaigns

Marketing Campaigns API

Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.

Campaigns

Campaigns related resources of the Marketing Campaigns API

A campaign requires a title to be created. In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID.

Create a Campaign [POST]

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
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"
}
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
titletitle can't be blank
titletitle is too long (maximum is 100 characters)
categoriescategories exceeds 10 category limit
html_contenthtml_content exceeds the 1MB limit
plain_contentplain_content exceeds the 1MB limit
sender_idsender_id does not exist
sender_idsender_id is not a verified sender identity
list_idslist_ids do not all exist
segment_idssegment_ids do not all exist
ip_poolThe ip pool you provided is invalid
suppression_group_idsuppression_group_id does not exist
unsubscribesEither suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.
The JSON you have submitted cannot be parsed.
You've reached your limit of 2500 campaigns. Please delete one or more and try again.

Get all Campaigns [GET]

Returns campaigns in reverse order they were created (newest first) Returns an empty array if no campaigns exist
URI Parameter Required Requirements Description
limit No number The maximum number of campaigns to return
Default: 10
offset No number The index of the first campaign to return, where 0 is the first campaign
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
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!",
      "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!",
      "status": "Sent"
    }
  ]
}

View a Campaign [GET]

URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 404 Error Messages

Field Error Message
not found

Delete a Campaign [DELETE]

URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 404 Error Messages

Field Error Message
not found

Update a Campaign [PATCH]

URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 400 Error Messages

Field Error Message
titletitle can't be blank
titletitle is too long (maximum is 100 characters)
categoriescategories exceeds 10 category limit
html_contenthtml_content exceeds the 1MB limit
plain_contentplain_content exceeds the 1MB limit
sender_idsender_id does not exist
sender_idsender_id is not a verified sender identity
list_idslist_ids do not all exist
segment_idssegment_ids do not all exist
ip_poolThe ip pool you provided is invalid
suppression_group_idsuppression_group_id does not exist
unsubscribesEither suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.
The JSON you have submitted cannot be parsed.
1
HTTP/1.1 403

Possible 403 Error Messages

Field Error Message
You may only update a campaign when it is in draft mode.
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
not found

Send a Campaign [POST]

URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 400 Error Messages

Field Error Message
subjectsubject can't be blank
sender_idsender_id can't be blank
plain_contentplain_content can't be blank, please provide plain text or html content
list_idsYou must select at least 1 segment or 1 list to send to.
unsubscribe_tagAn [unsubscribe] tag in both your html and plain content is required to send a campaign.
suppression_group_idEither a suppression_group_id or custom_unsubscribe_url is required to send a 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

Possible 403 Error Messages

Field Error Message
You may only send a campaign when it is in draft mode.
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
not found
1
HTTP/1.1 500

Possible 500 Error Messages

Field Error Message
Failed to send your campaign.

Schedule a Campaign [POST]

URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 400 Error Messages

Field Error Message
subjectsubject can't be blank
sender_idsender_id can't be blank
plain_contentplain_content can't be blank, please provide plain text or html content
list_idsYou must select at least 1 segment or 1 list to send to.
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.
suppression_group_idEither a suppression_group_id or custom_unsubscribe_url is required to send a campaign.
The JSON you have submitted cannot be parsed.
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

Possible 403 Error Messages

Field Error Message
You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
not found

Update a Scheduled Campaign [PATCH]

Changes the send_at time for the specified campaign.
URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 400 Error Messages

Field Error Message
The JSON you have submitted cannot be parsed.
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

Possible 403 Error Messages

Field Error Message
send_atYou cannot update the send_at value of non-scheduled campaign.
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
not found

View Scheduled Time of a Campaign [GET]

URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 404 Error Messages

Field Error Message
not found

Unschedule a Scheduled Campaign [DELETE]

A successful unschedule will return a 204. If the specified campaign is in the process of being sent, the only option is to cancel (a different method).
URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

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

Possible 403 Error Messages

Field Error Message
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

Possible 404 Error Messages

Field Error Message
not found

Send a Test Campaign [POST]

To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"]
URI Parameter Required Requirements Description
campaign_id Yes number The id of the campaign

Request

1
POST https://api.sendgrid.com/v3/campaigns/{campaign_id}/schedules/test HTTP/1.1
Request Body
1
2
3
{
  "to": "your.email@example.com"
}

Response

1
HTTP/1.1 204
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
The JSON you have submitted cannot be parsed.
toPlease provide an email address to which the test should be sent.
toYou can only send tests to 10 addresses at a time.
subjectPlease add a subject to your campaign before sending a test.
plain_contentPlain content and html content can't both be blank. Please set one of these values before sending a test.
sender_idPlease assign a sender identity to your campaign before sending a test.
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
not found