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.** Returns campaigns in reverse order they were created (newest first). Returns an empty array if no campaigns exist. You 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.** This 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.** If 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.** 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).' 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.** Normally 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.** To 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 Status: type: string enum: - Scheduled 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 Editor: type: string enum: - code - design 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 parameters: 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 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