SendGrid Single Sends API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Single Sends 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: Single Sends
  description: Twilio SendGrid Marketing Campaigns Single Sends API
paths:
  /v3/marketing/singlesends:
    post:
      operationId: CreateSingleSend
      summary: Create Single Send
      tags:
      - Single Sends
      description: '**This endpoint allows you to create a new Single Send.**


        Please note that if you are migrating from the previous version of Single Sends, you no longer need to pass a template ID with your request to this endpoint. Instead, you will pass all template data in the `email_config` object.


        This endpoint will create a draft of the Single Send but will not send it or schedule it to be sent. Any `send_at` property value set with this endpoint will prepopulate the Single Send''s send date. However, the Single Send will remain an unscheduled draft until it''s updated with the [**Schedule Single Send**](https://docs.sendgrid.com/api-reference/single-sends/schedule-single-send) endpoint or SendGrid application UI.'
      requestBody:
        $ref: '#/components/requestBodies/SinglesendRequestBody'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SinglesendResponse'
              examples:
                response:
                  value:
                    name: Example API Created Single Send
                    id: 27c21bbf-a12c-440b-b8bf-c526975328ca
                    status: scheduled
                    created_at: '2020-05-18T17:28:27.272Z'
                    categories:
                    - unique opens
                    email_config:
                      subject: ''
                      html_content: ''
                      plain_content: ''
                      generate_plain_content: true
                      editor: code
                      suppression_group_id: null
                      custom_unsubscribe_url: null
                      sender_id: null
                      ip_pool: null
                    send_to:
                      list_ids:
                      - f2fe66a1-43f3-4e3a-87b1-c6a600d805f0
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
    get:
      operationId: ListSingleSend
      summary: Get All Single Sends
      tags:
      - Single Sends
      description: '**This endpoint allows you to retrieve all your Single Sends.**


        Returns all of your Single Sends with condensed details about each, including the Single Sends'' IDs. For more details about an individual Single Send, pass the Single Send''s ID to the `/marketing/singlesends/{id}` endpoint.'
      parameters:
      - name: page_size
        in: query
        schema:
          type: integer
      - name: page_token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/SinglesendResponseShort'
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
    delete:
      operationId: DeleteSingleSends
      summary: Bulk Delete Single Sends
      tags:
      - Single Sends
      description: '**This endpoint allows you to delete multiple Single Sends using an array of Single Sends IDs.**


        To first retrieve all your Single Sends'' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.


        Please note that a DELETE request is permanent, and your Single Sends will not be recoverable after deletion.'
      parameters:
      - name: ids
        in: query
        description: Single Send IDs to delete
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 50
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
  /v3/marketing/singlesends/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: DuplicateSingleSend
      summary: Duplicate Single Send
      tags:
      - Single Sends
      description: "**This endpoint allows you to duplicate an existing Single Send using its Single Send ID.**\n\nDuplicating a Single Send is useful when you want to create a Single Send but don't want to start from scratch. Once duplicated, you can update or edit the Single Send by making a PATCH request to the `/marketing/singlesends/{id}` endpoint.\n \nIf you leave the `name` field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text “Copy of ” prepended to it. The `name` field length is limited to 100 characters, so the end of the new Single Send name, including “Copy of ”, will be trimmed if the name exceeds this limit."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: The name of the duplicate Single Send. If you choose to leave the name field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text 'Copy of ' prepended to it. The end of the new Single Send name, including 'Copy of ', will be trimmed if the name exceeds the character limit.
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SinglesendResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
    patch:
      operationId: UpdateSingleSend
      summary: Update Single Send
      tags:
      - Single Sends
      description: '**This endpoint allows you to update a Single Send using a Single Send ID.**


        You only need to pass the properties you want to update. Any blank or missing properties will remain unaltered.


        This endpoint will update a draft of the Single Send but will not send it or schedule it to be sent. Any `send_at` property value set with this endpoint will prepopulate the Single Send''s send date. However, the Single Send will remain an unscheduled draft until it''s updated with the [**Schedule Single Send**](https://docs.sendgrid.com/api-reference/single-sends/schedule-single-send) endpoint or SendGrid application UI.'
      requestBody:
        $ref: '#/components/requestBodies/SinglesendRequestBody'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SinglesendResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
    get:
      operationId: GetSingleSend
      summary: Get Single Send by ID
      tags:
      - Single Sends
      description: '**This endpoint allows you to retrieve details about one Single Send using a Single Send ID.**


        You can retrieve all of your Single Sends by making a GET request to the `/marketing/singlesends` endpoint.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SinglesendResponse'
              examples:
                response:
                  value:
                    name: single-send-1
                    id: 2f6dec81-43b9-4c67-a890-3a38cb63b54a
                    status: scheduled
                    created_at: '2020-12-13T16:24:42.013Z'
                    send_to:
                      segment_ids:
                      - dad84de3-bec4-4e04-b132-2cbfd4bb3789
                      - 7dce758d-1155-4102-88d2-ca65565ac98b
                      all: true
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
    delete:
      operationId: DeleteSingleSend
      summary: Delete Single Send by ID
      tags:
      - Single Sends
      description: '**This endpoint allows you to delete one Single Send using a Single Send ID.**


        To first retrieve all your Single Sends'' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.


        Please note that a `DELETE` request is permanent, and your Single Send will not be recoverable after deletion.'
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
  /v3/marketing/singlesends/{id}/schedule:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    put:
      operationId: ScheduleSingleSend
      summary: Schedule Single Send
      tags:
      - Single Sends
      description: '**This endpoint allows you to send a Single Send immediately or schedule it to be sent at a later time.**


        To send your message immediately, set the `send_at` property value to the string `now`. To schedule the Single Send for future delivery, set the `send_at` value to your desired send time in [ISO 8601 date time format](https://www.iso.org/iso-8601-date-and-time-format.html) (`yyyy-MM-ddTHH:mm:ssZ`).'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                send_at:
                  type: string
                  description: The ISO 8601 time at which to send the Single Send. This must be in future or the string `now`. SendGrid [Mail Send](https://docs.sendgrid.com/api-reference/mail-send/mail-send) emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to emails sent via [Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns/).
                  format: date-time
              required:
              - send_at
              example:
                send_at: '3752-01-28T23:21:52.575Z'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  send_at:
                    type: string
                    description: The ISO 8601 time at which to send the Single Send. This must be in future or the string `now`. SendGrid [Mail Send](https://docs.sendgrid.com/api-reference/mail-send/mail-send) emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to emails sent via [Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns/).
                    format: date-time
                  status:
                    type: string
                    $ref: '#/components/schemas/Status'
              examples:
                response:
                  value:
                    send_at: '3752-01-28T23:21:52.575Z'
                    status: scheduled
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
    delete:
      operationId: DeleteScheduledSingleSend
      summary: Delete Single Send Schedule
      tags:
      - Single Sends
      description: '**This endpoint allows you to cancel a scheduled Single Send using a Single Send ID.**


        Making a DELETE request to this endpoint will cancel the scheduled sending of a Single Send. The request will not delete the Single Send itself. Deleting a Single Send can be done by passing a DELETE request to `/marketing/singlesends/{id}`.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SinglesendSchedule'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
  /v3/marketing/singlesends/categories:
    get:
      operationId: ListCategory
      summary: Get All Categories
      tags:
      - Single Sends
      description: '**This endpoint allows you to retrieve all the categories associated with your Single Sends.**


        This endpoint will return your latest 1,000 categories.'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    uniqueItems: true
                    maxItems: 1000
                    description: list of latest one thousand unique categories associated with all Single Sends in ascending order
                    items:
                      type: string
              examples:
                response:
                  value:
                    categories:
                    - equipment
                    - shoes
                    - sports
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
  /v3/marketing/singlesends/search:
    post:
      operationId: SearchSingleSend
      summary: Get Single Sends Search
      tags:
      - Single Sends
      description: "**This endpoint allows you to search for Single Sends based on specified criteria.**\n\nYou can search for Single Sends by passing a combination of values using the `name`, `status`, and `categories` request body fields.\n\nFor example, if you want to search for all Single Sends that are \"drafts\" or \"scheduled\" and also associated with the category \"shoes,\" your request body may look like the example below.\n\n```javascript\n{\n  \"status\": [\n    \"draft\",\n    \"scheduled\"\n  ],\n  \"categories\": [\n    \"shoes\"\n  ],\n}\n```"
      parameters:
      - name: page_size
        in: query
        schema:
          type: integer
      - name: page_token
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SinglesendSearch'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/SinglesendResponseShort'
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
              examples:
                response:
                  value:
                    result:
                    - id: df25ffdf-6a96-458a-9419-6d87d3094c6b
                      name: single-send-1
                      status: triggered
                      categories:
                      - shoes
                      is_abtest: true
                      abtest: null
                      updated_at: '3263-04-09T09:05:08.193Z'
                      created_at: '4739-10-29T07:11:32.476Z'
                      send_at: '2471-05-31T15:46:18.797Z'
                    _metadata:
                      self: https://a/nwNSrPSWt7d
                      prev: https://a/P0Enoayd
                      next: https://a/DYEsTUDww9-
                      count: 1
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        error_id:
                          type: string
components:
  schemas:
    SinglesendRequest:
      title: singlesend_request
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: The name of the Single Send.
        categories:
          type: array
          uniqueItems: true
          maxItems: 10
          description: The categories to associate with this Single Send.
          items:
            type: string
        send_at:
          type: string
          description: Set this property to an ISO 8601 formatted date-time when you would like to send the Single Send. Please note that any `send_at` property value set with this endpoint will prepopulate the send date in the SendGrid user interface (UI). However, the Single Send will remain an unscheduled draft until it's updated with the [**Schedule Single Send**](https://docs.sendgrid.com/api-reference/single-sends/schedule-single-send) endpoint or SendGrid application UI. Additionally, the `now` keyword is a valid `send_at` value only when using the Schedule Single Send endpoint. Setting this property to `now` with this endpoint will cause an error.
          format: date-time
          nullable: true
        send_to:
          type: object
          properties:
            list_ids:
              type: array
              description: The recipient List IDs that will receive the Single Send.
              maxItems: 50
              items:
                type: string
                format: uuid
            segment_ids:
              type: array
              description: The recipient Segment IDs that will receive the Single Send.
              maxItems: 10
              items:
                type: string
                format: uuid
            all:
              type: boolean
              description: Set to `true` to send to All Contacts. If set to `false`, at least one `list_ids` or `segment_ids` value must be provided before the Single Send is scheduled to be sent to recipients.
              default: false
        email_config:
          type: object
          properties:
            subject:
              type: string
              description: The subject line of the Single Send. Do not include this field when using a `design_id`.
            html_content:
              type: string
              description: The HTML content of the Single Send. Do not include this field when using a `design_id`.
            plain_content:
              type: string
              description: The plain text content of the Single Send. Do not include this field when using a `design_id`.
            generate_plain_content:
              type: boolean
              description: If set to `true`, `plain_content` is always generated from `html_content`. If set to false, `plain_content` is not altered.
              default: true
            design_id:
              type: string
              description: A `design_id` can be used in place of `html_content`, `plain_content`, and/or `subject`. You can retrieve a design's ID from the ["List Designs" endpoint](https://docs.sendgrid.com/api-reference/designs-api/list-designs) or by pulling it from the design's detail page URL in the Marketing Campaigns App.
            editor:
              type: string
              description: The editor — `"design"` or `"code"` — used to modify the Single Send's design in the Marketing Campaigns App.
              default: code
              $ref: '#/components/schemas/Editor'
            suppression_group_id:
              description: The ID of the Suppression Group to allow recipients to unsubscribe — you must provide this or the `custom_unsubscribe_url`.
              nullable: true
              type: integer
            custom_unsubscribe_url:
              description: The URL allowing recipients to unsubscribe — you must provide this or the `suppression_group_id`.
              format: uri
              nullable: true
              type: string
            sender_id:
              description: The ID of the verified Sender. You can retrieve a verified Sender's ID from the ["Get Verified Senders" endpoint](https://www.twilio.com/docs/sendgrid/api-reference/sender-verification/get-all-verified-senders) or by pulling it from the Sender's detail page URL in the SendGrid App.
              nullable: true
              type: integer
            ip_pool:
              description: The name of the IP Pool from which the Single Send emails are sent.
              nullable: true
              type: string
      required:
      - name
    Type:
      type: string
      enum:
      - subject
      - content
    SinglesendSchedule:
      title: singlesend-schedule
      type: object
      properties:
        send_at:
          type: string
          format: date-time
          description: The ISO 8601 time at which to send the Single Send. This must be in future or the string `now`. SendGrid [Mail Send](https://docs.sendgrid.com/api-reference/mail-send/mail-send) emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to emails sent via [Marketing Campaigns](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns/).
        status:
          type: string
          $ref: '#/components/schemas/Status1'
      required:
      - send_at
    SinglesendResponseShort:
      title: singlesend_response_short
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: name of the Single Send
        abtest:
          $ref: '#/components/schemas/AbTestSummary'
        status:
          type: string
          description: current status of the Single Send
          $ref: '#/components/sch

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