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.
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: [email protected]
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: [email protected]
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: [email protected]
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: [email protected]
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: [email protected]
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: [email protected]
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/LinkBranding200'
examples:
response:
value:
id: 1
domain: example.com
subdomain: mail
username: [email protected]
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: [email protected]
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: [email protected]
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 <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: <subuser-username>`). 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