openapi: 3.1.0 security: - BearerAuth: [] info: title: Twilio SendGrid Integrations API 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](https://segment.com/docs). 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 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: Id: type: string description: The unique ID of an Integration. properties: integration_id: type: string example: '12345' Destination: type: string description: The third-party application you would like to forward your email events to. enum: - Segment 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. 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. 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' IntegrationNotFound: type: object properties: message: type: string description: The error message tells you the cause of failure. example: integration does not exist (abc) InternalError: type: object properties: message: type: string description: The error message tells you the cause of failure. example: internal error 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. 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. 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 Destination1: type: string enum: - Segment Items: 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 Items1: type: string enum: - drop - processed - deferred - group_unsubscribe - bounce - delivered - click - unsubscribe - open - group_resubscribe - spamreport - machine_opened DestinationRegion1: type: string enum: - EU - US Items2: type: string enum: - drop - processed - deferred - group_unsubscribe - bounce - delivered - click - unsubscribe - open - group_resubscribe - spamreport - machine_opened DestinationRegion2: type: string enum: - EU - US Destination3: type: string enum: - Segment responses: {} examples: {} requestBodies: {} headers: {} securitySchemes: BearerAuth: type: http scheme: bearer description: Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header. tags: - name: External Integration Endpoints description: Third-Party Integrations for SendGrid Event Export