{ "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" } ] }