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\n\ To 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**. You 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.** You 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.** You 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.** Your 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. You 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.** You 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.** Link 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.** The 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: * 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) * Legacy branded links (migrated from the whitelabel wizard) * Default SendGrid-branded links (i.e., `100.ct.sendgrid.net`) You 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.** Link 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.** Link 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). Your 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