{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Link Branding API", "summary": "The Twilio SendGrid Link Branding API allows you to configure your domain settings so that all of the click-tracked links, opens, and images in your emails are served from your domain rather than `sendgrid.net`.", "description": "The Twilio SendGrid Link Branding API allows you to configure your domain settings so that all of the click-tracked links, opens, and images in your emails are served from your domain rather than `sendgrid.net`. Spam filters and recipient servers look at the links within emails to determine whether the email appear trustworthy. They use the reputation of the root domain to determine whether the links can be trusted.\n\nYou can also manage Link Branding in the **Sender Authentication** section of the Twilio SendGrid application user interface.\n\n See [**How to Set Up Link Branding**](https: //sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) for more information.", "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": "link_branding" } }, "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/whitelabel/links": { "post": { "operationId": "CreateBrandedLink", "summary": "Create a branded link", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to create a new branded link.**\n\nTo create the link branding, supply the root domain and, optionally, the subdomain \u2014 these go into separate fields in your request body. The root domain should match your FROM email address. If you provide a subdomain, it must be different from the subdomain you used for authenticating your domain.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "The root domain for the subdomain that you are creating the link branding for. This should match your FROM email address." }, "subdomain": { "type": "string", "description": "The subdomain to create the link branding for. Must be different from the subdomain you used for authenticating your domain." }, "default": { "type": "boolean", "description": "Indicates if you want to use this link branding as the default or fallback. When setting a new default, the existing default link branding will have its default status removed automatically.", "$ref": "#/components/schemas/Default" }, "region": { "type": "string", "default": "us", "description": "The region of the IP address. Can be `eu` or `us`.", "$ref": "#/components/schemas/Region" } }, "required": [ "domain" ], "example": { "domain": "example.com", "subdomain": "mail", "default": true } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBranding200" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } } } } } }, "get": { "operationId": "ListBrandedLink", "summary": "Retrieve all branded links", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to retrieve all branded links**.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of results returned per page.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkBranding200" } }, "examples": { "response": { "value": [ { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": true, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } }, { "id": 2, "domain": "example2.com", "subdomain": "news", "username": "john@example.com", "user_id": 8, "default": false, "valid": false, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "news.example2.com", "data": "sendgrid.net" }, "owner_cname": { "valid": false, "type": "cname", "host": "8.example2.com", "data": "sendgrid.net" } } } ] } } } } } } } }, "/v3/whitelabel/links/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the branded link you want to retrieve.", "required": true, "schema": { "type": "integer" } } ], "get": { "operationId": "GetBrandedLink", "summary": "Retrieve a branded link", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to retrieve a specific branded link by providing its ID.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBranding200" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } } } } } }, "patch": { "operationId": "UpdateBrandedLink", "summary": "Update a branded link", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to update a specific branded link. You can use this endpoint to change a branded link's default status.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "default": { "type": "boolean", "description": "Indicates if the branded link is set as the default. When setting a new default, the existing default link branding will have its default status removed automatically.", "$ref": "#/components/schemas/Default1" } }, "example": { "default": true } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBranding200" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": true, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } } } } } }, "delete": { "operationId": "DeleteBrandedLink", "summary": "Delete a branded link", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to delete a branded link.**\n\nYour request will receive a response with a 204 status code if the deletion was successful. The call does not return the link's details, so if you wish to record these make sure you call the \"Retrieve a branded link\" endpoint *before* you request its deletion.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" } } } }, "/v3/whitelabel/links/{id}/validate": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the branded link that you want to validate.", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "ValidateBrandedLink", "summary": "Validate a branded link", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to validate a branded link.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the branded link." }, "valid": { "type": "boolean", "description": "Indicates if the link branding is valid.", "$ref": "#/components/schemas/Valid" }, "validation_results": { "type": "object", "description": "The individual validation results for each of the DNS records associated with this branded link.", "required": [ "domain_cname" ], "properties": { "domain_cname": { "type": "object", "description": "The DNS record generated for the sending domain used for this branded link.", "required": [ "valid", "reason" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this DNS record is valid.", "$ref": "#/components/schemas/Valid1" }, "reason": { "type": "string", "nullable": true, "description": "Null if the DNS record is valid. If the DNS record is invalid, this will explain why." } } }, "owner_cname": { "type": "object", "description": "The DNS record created to verify the branded link.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid.", "$ref": "#/components/schemas/Valid2" }, "reason": { "type": "string", "nullable": true, "description": "Null if valid. If the DNS record is invalid, this will explain why." } }, "required": [ "valid", "reason" ] } } } }, "required": [ "id", "valid", "validation_results" ] }, "examples": { "response": { "value": { "id": 1, "valid": true, "validation_results": { "domain_cname": { "valid": false, "reason": "Expected CNAME to match \"sendgrid.net.\" but found \"example.com.\"." }, "owner_cname": { "valid": true, "reason": null } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The reasons why the validation failed.", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "The reason why the link whitelabel could not be validated." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "examples": { "response": { "value": { "errors": [ { "message": "internal error getting CNAME" } ] } } } } } } } } }, "/v3/whitelabel/links/{link_id}/subuser": { "parameters": [ { "name": "link_id", "in": "path", "description": "The ID of the branded link you want to associate.", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "AssociateBrandedLinkWithSubuser", "summary": "Associate a branded link with a subuser", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to associate a branded link with a subuser account.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The username of the subuser account that you want to associate the branded link with." } }, "example": { "username": "jane@example.com" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBranding200" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } } } } } } }, "/v3/whitelabel/links/default": { "get": { "operationId": "ListDefaultBrandedLink", "summary": "Retrieve the default branded link", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to retrieve the default branded link.**\n\nThe default branded link is the actual URL to be used when sending messages. If you have more than one branded link, the default is determined by the following order:\n\n* The validated branded link marked as `default` (set when you call the \"Create a branded link\" endpoint or by calling the \"Update a branded link\" endpoint on an existing link)\n* Legacy branded links (migrated from the whitelabel wizard)\n* Default SendGrid-branded links (i.e., `100.ct.sendgrid.net`)\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "domain", "in": "query", "description": "The domain to match against when finding the default branded link.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBranding200" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } } } } } } }, "/v3/whitelabel/links/subuser": { "get": { "operationId": "ListSubuserBrandedLink", "summary": "Retrieve a subuser's branded link", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to retrieve the branded link associated with a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and then validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", "parameters": [ { "name": "username", "in": "query", "description": "The username of the subuser to retrieve associated branded links for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkBranding200" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } } } } } }, "delete": { "operationId": "DisassociateBrandedLinkFromSubuser", "summary": "Disassociate a branded link from a subuser", "tags": [ "Link Branding" ], "description": "**This endpoint allows you to take a branded link away from a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).\n\nYour request will receive a response with a 204 status code if the disassociation was successful.", "parameters": [ { "name": "username", "in": "query", "description": "The username of the subuser account that you want to disassociate a branded link from.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } } } } }, "components": { "schemas": { "LinkBranding200": { "title": "Link Branding 200 Response", "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the branded link." }, "domain": { "type": "string", "description": "The root domain of the branded link." }, "subdomain": { "type": "string", "description": "The subdomain used to generate the DNS records for this link branding. This subdomain must be different from the subdomain used for your authenticated domain." }, "username": { "type": "string", "description": "The username of the account that this link branding is associated with." }, "user_id": { "type": "integer", "description": "The ID of the user that this link branding is associated with." }, "default": { "type": "boolean", "description": "Indicates if this is the default link branding.", "$ref": "#/components/schemas/Default2" }, "valid": { "type": "boolean", "description": "Indicates if this link branding is valid.", "$ref": "#/components/schemas/Valid3" }, "legacy": { "type": "boolean", "description": "Indicates if this link branding was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create new link branding if you need to update it.", "$ref": "#/components/schemas/Legacy" }, "dns": { "type": "object", "description": "The DNS records generated for this link branding.", "required": [ "domain_cname" ], "properties": { "domain_cname": { "type": "object", "description": "The DNS record generated to point to your link branding subdomain.", "required": [ "valid", "type", "host", "data" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid.", "$ref": "#/components/schemas/Valid4" }, "type": { "type": "string", "description": "The type of DNS record that was generated.", "$ref": "#/components/schemas/Type" }, "host": { "type": "string", "description": "The domain that this link branding will use for the links in your email." }, "data": { "type": "string", "description": "The domain that the DNS record points to." } } }, "owner_cname": { "type": "object", "description": "The DNS record generated to verify who created the link branding.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid.", "$ref": "#/components/schemas/Valid5" }, "type": { "type": "string", "description": "The type of DNS record generated.", "$ref": "#/components/schemas/Type1" }, "host": { "type": "string", "description": "Used to verify the link branding. The subdomain of this domain is the ID of the user who created the link branding." }, "data": { "type": "string", "description": "The domain that the DNS record points to." } }, "required": [ "valid", "host", "data" ] } } } }, "required": [ "id", "domain", "username", "user_id", "default", "valid", "legacy", "dns" ] }, "Default": { "type": "boolean", "enum": [ true, false ] }, "Region": { "type": "string", "enum": [ "eu", "us" ] }, "Default1": { "type": "boolean", "enum": [ true, false ] }, "Valid": { "type": "boolean", "enum": [ true, false ] }, "Valid1": { "type": "boolean", "enum": [ true, false ] }, "Valid2": { "type": "boolean", "enum": [ true, false ] }, "Default2": { "type": "boolean", "enum": [ true, false ] }, "Valid3": { "type": "boolean", "enum": [ true, false ] }, "Legacy": { "type": "boolean", "enum": [ true, false ] }, "Valid4": { "type": "boolean", "enum": [ true, false ] }, "Type": { "type": "string", "enum": [ "cname", "txt", "mx" ] }, "Valid5": { "type": "boolean", "enum": [ true, false ] }, "Type1": { "type": "string", "enum": [ "cname", "txt", "mx" ] } }, "responses": {}, "parameters": { "OnBehalfOf": { "name": "on-behalf-of", "in": "header", "description": "The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.", "required": false, "schema": { "type": "string" } } }, "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": "Link Branding", "description": "Twilio SendGrid Link Branding API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }