SendGrid External Integration Endpoints API

openapi: 3.2.0
info:
  title: Twilio SendGrid Integrations External Integration Endpoints…
  summary: The Integrations API allows you to send SendGrid email events to third-party applications.
  description: Integrations allows you to connect your SendGrid applications with third-party services and forward SendGrid email events to those external applications. Currently, Integrations supports event forwarding to Segment. You can use this API to create, delete, view, and update your Integrations.
  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: integrations
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: External Integration Endpoints
  description: Third-Party Integrations for SendGrid Event Export
paths:
  /v3/marketing/integrations:
    get:
      tags:
      - External Integration Endpoints
      summary: ListIntegration
      description: This endpoint returns all the Integrations for the user making this call.
      operationId: GetIntegrationsByUser
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Integration'
              example:
                result:
                - user_id: '12345'
                  integration_id: 5a1234
                  filters:
                    email_events:
                    - processed
                    - open
                  properties:
                    write_key: a123456
                    destination_region: US
                  label: Untitled Integration
                  destination: Segment
        '403':
          description: Forbidden. You may not have the required API token scope.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Forbidden'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InternalError'
    post:
      tags:
      - External Integration Endpoints
      summary: CreateIntegration
      description: This endpoint creates an Integration for email event forwarding. Each Integration has a maximum number of allowed Integration instances per user. For example, users can create up to 10 Segment Integrations.
      operationId: AddIntegration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationInput'
            example:
              filters:
                email_events:
                - click
                - drop
                - open
                - processed
                - delivered
              destination: Segment
              label: optional label
              properties:
                destination_region: US
                write_key: a123456
        required: true
      responses:
        '201':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
              example:
                user_id: '12345'
                integration_id: 5a1234
                filters:
                  email_events:
                  - click
                  - drop
                  - open
                  - processed
                  - delivered
                destination: Segment
                label: optional label
                properties:
                  destination_region: US
                  write_key: a123456
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvalidRequest'
        '403':
          description: Forbidden. You may have hit the max number of allowed Integrations or may not have required API token scope.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Forbidden'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InternalError'
    delete:
      tags:
      - External Integration Endpoints
      summary: DeleteBulkIntegration
      description: This endpoint deletes Integrations.
      operationId: DeleteIntegration
      parameters:
      - name: ids
        in: query
        description: Comma-delimited Integration IDs for the Integrations to delete.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Id'
        required: true
      responses:
        '204':
          description: Successful Operation
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvalidDeleteRequest'
        '403':
          description: Forbidden. You may not have the required API token scope.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found. The Integration you specified was not found.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationNotFound'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InternalError'
  /v3/marketing/integrations/{id}:
    get:
      tags:
      - External Integration Endpoints
      summary: GetIntegration
      description: This endpoint returns the data for a specific Integration.
      operationId: FindIntegrationById
      parameters:
      - name: id
        in: path
        description: The ID of the Integration you would like to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
              example:
                user_id: '12345'
                integration_id: 5a1234
                filters:
                  email_events:
                  - processed
                  - open
                properties:
                  write_key: a123456
                  destination_region: US
                label: Untitled Integration
                destination: Segment
        '403':
          description: Forbidden. You may not have the required API token scope.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found. The Integration you specified was not found.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationNotFound'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InternalError'
    patch:
      tags:
      - External Integration Endpoints
      summary: UpdateIntegration
      description: This endpoint updates an existing Integration.
      operationId: UpdateIntegration
      parameters:
      - name: id
        in: path
        description: The ID of the Integration you would like to update.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationPatch'
            example:
              filters:
                email_events:
                - processed
                - open
              properties:
                write_key: a123456
                destination_region: US
              label: Untitled Integration
              destination: Segment
        required: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
              example:
                user_id: '12345'
                integration_id: 5a1234
                filters:
                  email_events:
                  - processed
                  - open
                properties:
                  write_key: a123456
                  destination_region: US
                label: Untitled Integration
                destination: Segment
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvalidRequest'
        '403':
          description: Forbidden. You may not have the required API token scope.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found. The Integration you specified was not found.
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationNotFound'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/InternalError'
components:
  schemas:
    Items1:
      type: string
      enum:
      - drop
      - processed
      - deferred
      - group_unsubscribe
      - bounce
      - delivered
      - click
      - unsubscribe
      - open
      - group_resubscribe
      - spamreport
      - machine_opened
    Destination3:
      type: string
      enum:
      - Segment
    Destination1:
      type: string
      enum:
      - Segment
    DestinationRegion2:
      type: string
      enum:
      - EU
      - US
    Items2:
      type: string
      enum:
      - drop
      - processed
      - deferred
      - group_unsubscribe
      - bounce
      - delivered
      - click
      - unsubscribe
      - open
      - group_resubscribe
      - spamreport
      - machine_opened
    DestinationRegion:
      type: string
      enum:
      - EU
      - US
    Destination2:
      type: string
      enum:
      - Segment
    InvalidDeleteRequest:
      type: object
      properties:
        message:
          type: string
          description: The error message tells you the cause of failure.
          example: IDs cannot be an empty string
        parameter:
          type: string
          example: ids[1]
          description: The parameter shows more information about where the error is. The number in the brackets is the invalid ID indexed.
    IntegrationNotFound:
      type: object
      properties:
        message:
          type: string
          description: The error message tells you the cause of failure.
          example: integration does not exist (abc)
    IntegrationPatch:
      type: object
      properties:
        destination:
          type: string
          description: The third-party application you would like to forward your email events to.
          $ref: '#/components/schemas/Destination1'
        filters:
          type: object
          description: The configurable filters for SendGrid to destination email event forwarding.
          properties:
            email_events:
              type: array
              description: The possible SendGrid email event types for event forwarding. Specify all the email event types that you would like to forward to the Integration's destination.
              items:
                type: string
                $ref: '#/components/schemas/Items'
        properties:
          type: object
          description: The properties of an Integration required to send events to a specific third-party application.
          properties:
            write_key:
              description: The write key provided by the Segment Source you'd like to have events forwarded to. Must be between 6 and 51 characters.
              type: string
              example: 1234-abc
            destination_region:
              description: The workspace region where the Segment Source write key lives.
              type: string
              $ref: '#/components/schemas/DestinationRegion'
        label:
          type: string
          default: Untitled Integration
          example: My New Segment Integration!
          description: The nickname for the Integration.
    Id:
      type: string
      description: The unique ID of an Integration.
      properties:
        integration_id:
          type: string
          example: '12345'
    InternalError:
      type: object
      properties:
        message:
          type: string
          description: The error message tells you the cause of failure.
          example: internal error
    IntegrationInput:
      type: object
      required:
      - destination
      - filters
      - properties
      properties:
        destination:
          type: string
          description: The third-party application you would like to forward your events to.
          $ref: '#/components/schemas/Destination2'
        filters:
          type: object
          required:
          - email_events
          description: The configurable filters for SendGrid to destination email event forwarding.
          properties:
            email_events:
              type: array
              description: The possible SendGrid email event types for event forwarding. Specify all the email event types that you would like to forward to the Integration's destination.
              items:
                type: string
                $ref: '#/components/schemas/Items1'
        properties:
          type: object
          description: The properties of an Integration required to send events to a specific third-party application.
          required:
          - write_key
          - destination_region
          properties:
            write_key:
              description: The write key provided by the Segment Source you'd like to have events forwarded to. Must be between 6 and 51 characters.
              type: string
              example: 1234-abc
            destination_region:
              description: The workspace region where the Segment Source write key lives.
              type: string
              $ref: '#/components/schemas/DestinationRegion1'
        label:
          type: string
          default: Untitled Integration
          example: My New Segment Integration!
          description: The nickname for the Integration.
    Forbidden:
      type: object
      properties:
        message:
          type: string
          description: The error message tells you the cause of failure.
          example: access forbidden. please ensure you have the correct scopes defined. see https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization#api-key-permissions-list
    Integration:
      type: object
      properties:
        integration_id:
          type: string
          description: The unique ID of an Integration.
          example: '12345'
        user_id:
          type: string
          example: '123456'
          description: Your Twilio SendGrid account ID.
        filters:
          type: object
          description: The configurable filters for SendGrid to destination email event forwarding.
          properties:
            email_events:
              type: array
              description: The possible SendGrid email event types for event forwarding. Specify all the email event types that you would like to forward to the Integration's destination.
              items:
                type: string
                $ref: '#/components/schemas/Items2'
        properties:
          type: object
          description: The properties of an Integration required to send events to a specific third-party application.
          properties:
            write_key:
              description: The write key provided by the Segment Source you'd like to have events forwarded to. Must be between 6 and 51 characters.
              type: string
              example: 1234-abc
            destination_region:
              description: The workspace region where the Segment Source write key lives.
              type: string
              $ref: '#/components/schemas/DestinationRegion2'
        label:
          type: string
          default: Untitled Integration
          example: My New Segment Integration!
          description: The nickname for the Integration.
        destination:
          type: string
          description: The third-party application you would like to forward your events to.
          $ref: '#/components/schemas/Destination3'
    InvalidRequest:
      type: object
      properties:
        message:
          type: string
          description: The error message tells you the cause of validation failure(s), separated by commas if there are multiple failures.
          example: destination_region must be EU or US, write_key must be at least 7 characters
        field:
          type: string
          example: request
          description: The field shows more information on where the error is when available.
    DestinationRegion1:
      type: string
      enum:
      - EU
      - US
    Items:
      type: string
      enum:
      - drop
      - processed
      - deferred
      - group_unsubscribe
      - bounce
      - delivered
      - click
      - unsubscribe
      - open
      - group_resubscribe
      - spamreport
      - machine_opened
  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.