{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Legacy Marketing Campaigns Campaigns API", "summary": "The Twilio SendGrid Legacy Marketing Campaigns Campaigns API allows you to manage your marketing email messages programmatically. SendGrid recommends [moving to the latest version of Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/migrating-from-legacy-marketing-campaigns) if you are using this API.", "description": "The Twilio SendGrid Legacy Marketing Campaigns Campaigns API allows you to manage your marketing email messages programmatically. This API is operational, but we recommend using the current version of Marketing Campaigns to manage your marketing messages with SendGrid [Single Sends](https://docs.sendgrid.com/api-reference/single-sends/) and [Automations](https://docs.sendgrid.com/ui/sending-email/getting-started-with-automation).\n\nSee [**Migrating from Legacy Marketing Campaigns**](https://docs.sendgrid.com/ui/sending-email/migrating-from-legacy-marketing-campaigns) for more information.", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio SendGrid Support", "url": "https://support.sendgrid.com/hc/en-us" }, "license": { "name": "MIT", "url": "https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE" }, "version": "1.0.0", "x-sendgrid": { "libraryPackage": "lmc_campaigns" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "The Twilio SendGrid v3 API" } ], "paths": { "/v3/campaigns": { "post": { "operationId": "CreateCampaign", "summary": "Create a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to create a campaign.**\n\nIn 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.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCampaignsRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaigns2xx" }, "examples": { "response": { "value": { "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": "

Check out our spring line!

", "plain_content": "Check out our spring line!", "status": "Draft" } } } } } }, "400": { "description": "The request was formatted incorrectly or missing required parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": "title", "message": "title can't be blank" }, { "field": "title", "message": "title is too long (maximum is 100 characters)" }, { "field": "categories", "message": "categories exceeds 10 category limit" }, { "field": "html_content", "message": "html_content exceeds the 1MB limit" }, { "field": "plain_content", "message": "plain_content exceeds the 1MB limit" }, { "field": "sender_id", "message": "sender_id does not exist" }, { "field": "sender_id", "message": "sender_id is not a verified sender identity" }, { "field": "list_ids", "message": "list_ids do not all exist" }, { "field": "segment_ids", "message": "segment_ids do not all exist" }, { "field": "ip_pool", "message": "The ip pool you provided is invalid" }, { "field": "suppression_group_id", "message": "suppression_group_id does not exist" }, { "field": "unsubscribes", "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." }, { "field": null, "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." } ] } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "operationId": "ListCampaign", "summary": "Retrieve all Campaigns", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to retrieve a paginated list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.\n\nYou can use the `limit` query parameter to set the page size. If your list contains more items than the page size permits, you can make multiple requests. Use the `offset` query parameter to control the position in the list from which to start retrieving additional items.", "parameters": [ { "name": "limit", "in": "query", "description": "`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used.", "schema": { "type": "integer", "minimum": 1, "default": 10 } }, { "$ref": "#/components/parameters/PaginationCommonOffset" }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Campaigns2xx" } } } }, "examples": { "response": { "value": { "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": "

Check out our spring line!

", "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": "

Last call for winter clothes!

", "plain_content": "Last call for winter clothes!", "status": "Sent" } ] } } } } } } } } }, "/v3/campaigns/{campaign_id}": { "parameters": [ { "name": "campaign_id", "in": "path", "description": "The id of the campaign you would like to retrieve.", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "GetCampaign", "summary": "Retrieve a single campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to retrieve a specific campaign.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } }, "custom_unsubscribe_url": { "type": "string" }, "html_content": { "type": "string" }, "id": { "type": "integer" }, "ip_pool": { "type": "string" }, "list_ids": { "type": "array", "items": { "type": "integer" } }, "plain_content": { "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "integer" } }, "sender_id": { "type": "integer" }, "status": { "type": "string" }, "subject": { "type": "string" }, "suppression_group_id": { "type": "integer" }, "title": { "type": "string" } } }, "examples": { "response": { "value": { "categories": [ "spring line" ], "custom_unsubscribe_url": "", "html_content": "

Check out our spring line!

", "id": 986724, "ip_pool": "marketing", "list_ids": [ 110 ], "plain_content": "Check out our spring line!", "segment_ids": [ 110 ], "sender_id": 124451, "status": "Draft", "subject": "New Products for Spring!", "suppression_group_id": 42, "title": "March Newsletter" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "authorization required" } ] } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } }, "delete": { "operationId": "DeleteCampaign", "summary": "Delete a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to delete a specific campaign.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "authorization required" } ] } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "patch": { "operationId": "UpdateCampaign", "summary": "Update a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to update a specific campaign.**\n\nThis is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Update a Campaign request", "type": "object", "properties": { "title": { "type": "string", "description": "The title of the campaign." }, "subject": { "type": "string", "description": "The subject line for your campaign." }, "categories": { "type": "array", "description": "The categories you want to tag on this campaign.", "items": { "type": "string" } }, "html_content": { "type": "string", "description": "The HTML content of this campaign." }, "plain_content": { "type": "string", "description": "The plain content of this campaign." } }, "required": [ "title", "subject", "categories", "html_content", "plain_content" ], "example": { "title": "May Newsletter", "subject": "New Products for Summer!", "categories": [ "summer line" ], "html_content": "

Check out our summer line!

", "plain_content": "Check out our summer line!" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaigns2xx" }, "examples": { "response": { "value": { "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": "

Check out our summer line!

", "plain_content": "Check out our summer line!", "status": "Draft" } } } } } }, "400": { "description": "The request was formatted incorrectly or missing required parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": "title", "message": "title can't be blank" }, { "field": "title", "message": "title is too long (maximum is 100 characters)" }, { "field": "categories", "message": "categories exceeds 10 category limit" }, { "field": "html_content", "message": "html_content exceeds the 1MB limit" }, { "field": "plain_content", "message": "plain_content exceeds the 1MB limit" }, { "field": "sender_id", "message": "sender_id does not exist" }, { "field": "sender_id", "message": "sender_id is not a verified sender identity" }, { "field": "list_ids", "message": "list_ids do not all exist" }, { "field": "segment_ids", "message": "segment_ids do not all exist" }, { "field": "ip_pool", "message": "The ip pool you provided is invalid" }, { "field": "suppression_group_id", "message": "suppression_group_id does not exist" }, { "field": "unsubscribes", "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." } ] } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "authorization required" } ] } } } } } }, "403": { "description": "You may only update a campaign when it is in draft mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "You may only update a campaign when it is in draft mode." } ] } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } } }, "/v3/campaigns/{campaign_id}/schedules": { "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "ScheduleCampaign", "summary": "Schedule a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**\n\nIf you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won't be going through our servers at the same times as everyone else's mail.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Schedule a Campaign request", "type": "object", "properties": { "send_at": { "type": "integer", "description": "The unix timestamp for the date and time you would like your campaign to be sent out." } }, "required": [ "send_at" ], "example": { "send_at": 1489771528 } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "title": "Schedule a Campaign response", "type": "object", "properties": { "id": { "type": "integer", "description": "The campaign ID." }, "send_at": { "type": "integer", "description": "The date time you scheduled your campaign to be sent." }, "status": { "type": "string", "description": "The status of your campaign.", "$ref": "#/components/schemas/Status" } }, "required": [ "id", "send_at", "status" ] }, "examples": { "response": { "value": { "id": 1234, "send_at": 1489771528, "status": "Scheduled" } } } } } }, "400": { "description": "The request was formatted incorrectly or missing required parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": "subject", "message": "subject can't be blank" }, { "field": "sender_id", "message": "sender_id can't be blank" }, { "field": "plain_content", "message": "plain_content can't be blank, please provide plain text or html content" }, { "field": "list_id", "message": "You must select at least 1 segment or 1 list to send to." }, { "field": "unsubscribe_tag", "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." }, { "field": "suppression_group_id", "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "authorization required" } ] } } } } } }, "403": { "description": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH." } ] } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } }, "patch": { "operationId": "UpdateScheduledCampaign", "summary": "Update a Scheduled Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Update a Scheduled Campaign request", "type": "object", "properties": { "send_at": { "type": "integer", "format": "int64" } }, "required": [ "send_at" ], "example": { "send_at": 1489451436 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "title": "Update a Scheduled Campaign response", "type": "object", "properties": { "id": { "type": "integer", "description": "The campaign ID" }, "send_at": { "type": "integer", "description": "The unix timestamp to send the campaign." }, "status": { "type": "string", "description": "The status of the schedule." } }, "required": [ "id", "send_at", "status" ] } } } }, "400": { "description": "The request was formatted incorrectly or you do not have enough credits to send this campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": "send_at", "message": "Please choose a future time for sending your campaign." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" } ] } } } } } }, "403": { "description": "\"send_at\": \"You cannot update the send_at value of non-scheduled campaign.\"", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": "send_at", "message": "You cannot update the send_at value of non-scheduled campaign." } ] } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } }, "get": { "operationId": "GetScheduledCampaign", "summary": "View Scheduled Time of a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to retrieve the date and time that a campaign has been scheduled to be sent.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "title": "View Scheduled Time of a Campaign response", "type": "object", "properties": { "send_at": { "type": "integer", "format": "int64" } }, "required": [ "send_at" ] }, "examples": { "response": { "value": { "send_at": 1490778528 } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } }, "delete": { "operationId": "UnScheduleCampaign", "summary": "Unschedule a Scheduled Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" }, "403": { "description": "The request was formatted incorrectly or missing required parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "This campaign is already In Progress." }, { "field": null, "message": "This campaign is already Sent." }, { "field": null, "message": "This campaign is already Paused." }, { "field": null, "message": "This campaign is already Canceled." } ] } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } } }, "/v3/campaigns/{campaign_id}/schedules/now": { "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "SendCampaign", "summary": "Send a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to immediately send an existing campaign.**\n\nNormally a POST request would have a body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "title": "Send a Campaign response", "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "status": { "type": "string" } }, "required": [ "id", "status" ] }, "examples": { "response": { "value": { "id": 1234, "status": "Scheduled" } } } } } }, "400": { "description": "The request was formatted incorrectly or you do not have enough credits to send this campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": "subject", "message": "subject can't be blank" }, { "field": "sender_id", "message": "sender_id can't be blank" }, { "field": "plain_content", "message": "plain_content can't be blank, please provide plain text or html content" }, { "field": "list_id", "message": "You must select at least 1 segment or 1 list to send to." }, { "field": "unsubscribe_tag", "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." }, { "field": "suppression_group_id", "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "authorization required" } ] } } } } } }, "403": { "description": "You may only send a campaign when it is in draft mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "You may only send a campaign when it is in draft mode." } ] } } } } } }, "404": { "description": "Not found\"", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } } }, "/v3/campaigns/{campaign_id}/schedules/test": { "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "SendTestCampaign", "summary": "Send a Test Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to send a test campaign.**\n\nTo send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "The email address that should receive the test campaign.", "format": "email" } }, "required": [ "to" ], "example": { "to": "your.email@example.com" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "title": "Send a Test Campaign request", "type": "object", "properties": { "to": { "type": "string" } }, "required": [ "to" ] } } } }, "400": { "description": "The request was formatted incorrectly or missing required parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": "send_at", "message": "Please choose a future time for sending your campaign." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "not found" } ] } } } } } } } } } }, "components": { "schemas": { "PostCampaignsRequest": { "title": "Campaigns Request", "type": "object", "properties": { "title": { "type": "string", "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." }, "subject": { "description": "The subject of your campaign that your recipients will see.", "nullable": true, "type": "string" }, "sender_id": { "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails.", "nullable": true, "type": "integer" }, "list_ids": { "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", "items": { "type": "integer" }, "nullable": true, "type": "array" }, "segment_ids": { "description": "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.", "items": { "type": "integer" }, "nullable": true, "type": "array" }, "categories": { "description": "The categories you would like associated to this campaign.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "suppression_group_id": { "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.", "nullable": true, "type": "integer" }, "custom_unsubscribe_url": { "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.", "nullable": true, "type": "string" }, "ip_pool": { "description": "The pool of IPs that you would like to send this email from.", "nullable": true, "type": "string" }, "html_content": { "description": "The HTML of your marketing email.", "nullable": true, "type": "string" }, "plain_content": { "description": "The plain text content of your emails.", "nullable": true, "type": "string" }, "editor": { "type": "string", "description": "The editor used in the UI.", "$ref": "#/components/schemas/Editor" } }, "required": [ "title" ], "example": { "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": "

Check out our summer line!

", "plain_content": "Check out our summer line!", "status": "Draft" } }, "Campaigns2xx": { "title": "Campaigns Response", "type": "object", "properties": { "title": { "type": "string", "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." }, "subject": { "description": "The subject of your campaign that your recipients will see.", "nullable": true, "type": "string" }, "sender_id": { "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails.", "nullable": true, "type": "integer" }, "list_ids": { "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", "items": { "type": "integer" }, "nullable": true, "type": "array" }, "segment_ids": { "description": "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.", "items": { "type": "integer" }, "nullable": true, "type": "array" }, "categories": { "description": "The categories you would like associated to this campaign.", "items": { "type": "string" }, "nullable": true, "type": "array" }, "suppression_group_id": { "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.", "nullable": true, "type": "integer" }, "custom_unsubscribe_url": { "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.", "nullable": true, "type": "string" }, "ip_pool": { "description": "The pool of IPs that you would like to send this email from.", "nullable": true, "type": "string" }, "html_content": { "description": "The HTML of your marketing email.", "nullable": true, "type": "string" }, "plain_content": { "description": "The plain text content of your emails.", "nullable": true, "type": "string" }, "editor": { "type": "string", "description": "The editor used in the UI.", "$ref": "#/components/schemas/Editor" }, "status": { "type": "string", "description": "The status of your campaign." }, "id": { "type": "integer" } }, "required": [ "status", "title" ] }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "An error message." }, "field": { "description": "When applicable, this property value will be the field that generated the error.", "nullable": true, "type": "string" }, "help": { "type": "object", "description": "When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error." } } } }, "id": { "type": "string", "description": "When applicable, this property value will be an error ID." } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } }, "Status": { "type": "string", "enum": [ "Scheduled" ] }, "Editor": { "type": "string", "enum": [ "code", "design" ] } }, "responses": {}, "parameters": { "OnBehalfOf": { "name": "on-behalf-of", "in": "header", "description": "The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.", "required": false, "schema": { "type": "string" } }, "PaginationCommonOffset": { "name": "offset", "in": "query", "required": false, "description": "The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "examples": {}, "requestBodies": {}, "headers": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header." } } }, "tags": [ { "name": "Campaigns API", "description": "Legacy Marketing Campaigns: Campaigns API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }