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.
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