Menu

Campaigns API

Elements that can be shared among more than one endpoint definition.

Create a Campaign

Create a Campaign

POST /campaigns

This endpoint allows you to create a campaign.

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. This information is not required when you create a campaign.

Authentication

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required
on-behalf-of
string
default: The subuser's username. This header generates the API call as if the subuser account was making the call.

Request Body

object
title
string

The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI.

required
subject
string

The subject of your campaign that your recipients will see.

sender_id
integer

The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails.

list_ids
array[integer]

The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs

segment_ids
array[integer]

The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. Segments are limited to 10 segment IDs.

categories
array[string]

The categories you would like associated to this campaign.

suppression_group_id
integer

The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.

custom_unsubscribe_url
string

This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.

ip_pool
string

The pool of IPs that you would like to send this email from.

html_content
string

The HTML of your marketing email.

plain_content
string

The plain text content of your emails.

editor
string

The editor used in the UI.

Allowed Values: code, design
{
  "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"
}

Responses

object
title
string

The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI.

required
subject
string

The subject of your campaign that your recipients will see.

sender_id
integer

The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails.

list_ids
array[integer]

The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs

segment_ids
array[integer]

The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. Segments are limited to 10 segment IDs.

categories
array[string]

The categories you would like associated to this campaign.

suppression_group_id
integer

The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.

custom_unsubscribe_url
string

This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.

ip_pool
string

The pool of IPs that you would like to send this email from.

html_content
string

The HTML of your marketing email.

plain_content
string

The plain text content of your emails.

editor
string

The editor used in the UI.

Allowed Values: code, design
status
string

The status of your campaign.

required
id
integer
{
  "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"
}
object
errors
array[object]
message
string

the error message

field
string

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.