# Update Integration ## API Overview An Integration is a connection from a SendGrid Marketing Campaign to a supported third-party application. Integrations with different external applications allow you to sync data and create a more cohesive cross-product data experience. Currently, only [Segment](https://segment.com/docs) Integrations are supported. Segment Integrations allow you to customize and automate email event forwarding to your Segment account. The Integrations API allows you to create, retrieve, update, and delete your Integrations. ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/marketing/integrations/{id}","method":"patch","servers":[{"url":"https://api.sendgrid.com","description":"for global users and subusers"},{"url":"https://api.eu.sendgrid.com","description":"for EU regional subusers"}]} ``` This endpoint updates an existing Integration. ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}}] ``` ### Path parameters ```json [{"name":"id","in":"path","description":"The ID of the Integration you would like to update.","required":true,"schema":{"type":"string"}}] ``` ### Request body ```json {"schema":{"type":"object","refName":"IntegrationPatch","modelName":"IntegrationPatch","properties":{"destination":{"type":"string","description":"The third-party application you would like to forward your email events to.","enum":["Segment"],"refName":"Destination1","modelName":"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","enum":["drop","processed","deferred","group_unsubscribe","bounce","delivered","click","unsubscribe","open","group_resubscribe","spamreport","machine_opened"],"refName":"Items","modelName":"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","enum":["EU","US"],"refName":"DestinationRegion","modelName":"DestinationRegion"}}},"label":{"type":"string","default":"Untitled Integration","example":"My New Segment Integration!","description":"The nickname for the Integration."}}},"example":{"filters":{"email_events":["processed","open"]},"properties":{"write_key":"a123456","destination_region":"US"},"label":"Untitled Integration","destination":"Segment"},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"200","schema":{"description":"Successful Operation","content":{"application/json":{"schema":{"type":"object","refName":"Integration","modelName":"Integration","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","enum":["drop","processed","deferred","group_unsubscribe","bounce","delivered","click","unsubscribe","open","group_resubscribe","spamreport","machine_opened"],"refName":"Items2","modelName":"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","enum":["EU","US"],"refName":"DestinationRegion2","modelName":"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.","enum":["Segment"],"refName":"Destination3","modelName":"Destination3"}}},"example":{"user_id":"12345","integration_id":"5a1234","filters":{"email_events":["processed","open"]},"properties":{"write_key":"a123456","destination_region":"US"},"label":"Untitled Integration","destination":"Segment"}}}}},{"responseCode":"400","schema":{"description":"Invalid Request","content":{"application/json":{"schema":{"properties":{"errors":{"type":"array","items":{"type":"object","refName":"InvalidRequest","modelName":"InvalidRequest","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."}}}}}}}}}},{"responseCode":"403","schema":{"description":"Forbidden. You may not have the required API token scope.","content":{"application/json":{"schema":{"properties":{"errors":{"type":"array","items":{"type":"object","refName":"Forbidden","modelName":"Forbidden","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 /docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/authorization#api-key-permissions-list"}}}}}}}}}},{"responseCode":"404","schema":{"description":"Not Found. The Integration you specified was not found.","content":{"application/json":{"schema":{"properties":{"errors":{"type":"array","items":{"type":"object","refName":"IntegrationNotFound","modelName":"IntegrationNotFound","properties":{"message":{"type":"string","description":"The error message tells you the cause of failure.","example":"integration does not exist (abc)"}}}}}}}}}},{"responseCode":"500","schema":{"description":"Internal Error","content":{"application/json":{"schema":{"properties":{"errors":{"type":"array","items":{"type":"object","refName":"InternalError","modelName":"InternalError","properties":{"message":{"type":"string","description":"The error message tells you the cause of failure.","example":"internal error"}}}}}}}}}}] ``` Update an Integration ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const id = "id"; const data = { filters: { email_events: ["processed", "open"], }, properties: { write_key: "a123456", destination_region: "US", }, label: "Untitled Integration", destination: "Segment", }; const request = { url: `/v3/marketing/integrations/${id}`, method: "PATCH", body: data, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) id = "id" data = { "filters": {"email_events": ["processed", "open"]}, "properties": {"write_key": "a123456", "destination_region": "US"}, "label": "Untitled Integration", "destination": "Segment", } response = sg.client.marketing.integrations._(id).patch(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var id = "id"; var data = @"{ ""filters"": { ""email_events"": [ ""processed"", ""open"" ] }, ""properties"": { ""write_key"": ""a123456"", ""destination_region"": ""US"" }, ""label"": ""Untitled Integration"", ""destination"": ""Segment"" }"; var response = await client.RequestAsync( method: SendGridClient.Method.PATCH, urlPath: $"marketing/integrations/{id}", requestBody: data); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; import org.json.JSONObject; import java.util.HashMap; import java.util.Arrays; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.PATCH); request.setEndpoint("/marketing/integrations/id"); request.setBody(new JSONObject(new HashMap() { { put("filters", new HashMap() { { put("email_events", Arrays.asList("processed", "open")); } }); put("properties", new HashMap() { { put("write_key", "a123456"); put("destination_region", "US"); } }); put("label", "Untitled Integration"); put("destination", "Segment"); } }).toString()); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/marketing/integrations/id", host) request.Method = "PATCH" request.Body = []byte(`{ "filters": { "email_events": [ "processed", "open" ] }, "properties": { "write_key": "a123456", "destination_region": "US" }, "label": "Untitled Integration", "destination": "Segment" }`) response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('{ "filters": { "email_events": [ "processed", "open" ] }, "properties": { "write_key": "a123456", "destination_region": "US" }, "label": "Untitled Integration", "destination": "Segment" }'); $id = "id"; try { $response = $sg->client ->marketing() ->integrations() ->_($id) ->patch($request_body); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) data = JSON.parse('{ "filters": { "email_events": [ "processed", "open" ] }, "properties": { "write_key": "a123456", "destination_region": "US" }, "label": "Untitled Integration", "destination": "Segment" }') id = "id" response = sg.client.marketing.integrations._(id).patch(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X PATCH "https://api.sendgrid.com/v3/marketing/integrations/id" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"filters": {"email_events": ["processed", "open"]}, "properties": {"write_key": "a123456", "destination_region": "US"}, "label": "Untitled Integration", "destination": "Segment"}' ```