openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Campaigns API API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  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: account_provisioning
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Campaigns API
  description: 'Legacy Marketing Campaigns: Campaigns API'
paths:
  /v3/campaigns:
    post:
      operationId: CreateCampaign
      summary: Create a Campaign
      tags:
      - Campaigns API
      description: '**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.'
      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: <html><head><title></title></head><body><p>Check out our spring line!</p></body></html>
                    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: <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
  /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: <html><head><title></title></head><body><p>Check out our spring line!</p></body></html>
                    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: <html><head><title></title></head><body><p>Check out our summer line!</p></body></html>
                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: <html><head><title></title></head><body><p>Check out our summer line!</p></body></html>
                    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:
     

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/sendgrid-campaigns-api-api-openapi.yml