--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/sendgrid/api-reference/link-branding/create-a-branded-link#article headline: Create a branded link description: Improve email trustworthiness with email link branding. Manage root domain reputation with API requests for custom link creation in Twilio SendGrid App. url: https://www.twilio.com/docs/sendgrid/api-reference/link-branding/create-a-branded-link inLanguage: en dateModified: 2025-09-17T16:47:58.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Create a branded link ## API Overview To serve all of the click-tracked links, opens, and images in your emails from your domain, use Email link branding. This replaces `sendgrid.net` for Global Email send or `eu.sendgrid.net` for Regional Email send with your domain. To determine whether the email looks trustworthy, [spam filters][spam-filter] and recipient servers look at the links within emails. To determine if they can trust the links, these systems check the [reputation][ers] of the root domain. To manage link branding, go to the [Sender Authentication section of the Twilio SendGrid App][Sender-Auth]. To learn more, see [How to set up link branding][link-branding]. [Sender-Auth]: https://app.sendgrid.com/settings/sender_auth [link-branding]: /docs/sendgrid/ui/account-and-settings/how-to-set-up-link-branding [spam-filter]: /docs/sendgrid/glossary/spam-filter [ers]: /docs/sendgrid/glossary/email-reputation-score ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/whitelabel/links","method":"post","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 allows you to create a new branded link.** To create the link branding, supply the root domain and, optionally, the subdomain — 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. You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}},{"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"},"refName":"#/components/parameters/OnBehalfOf","modelName":"__components_parameters_OnBehalfOf"}] ``` ### Request body ```json {"schema":{"type":"object","required":["domain"],"example":{"domain":"example.com","subdomain":"mail","default":true},"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.","enum":[true,false],"refName":"Default","modelName":"Default"},"region":{"type":"string","default":"us","description":"The region of the IP address. Can be `eu` or `us`.","enum":["eu","us"],"refName":"Region","modelName":"Region"}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"201","schema":{"description":"","content":{"application/json":{"schema":{"title":"Link Branding 200 Response","type":"object","required":["id","domain","username","user_id","default","valid","legacy","dns"],"refName":"LinkBranding200","modelName":"LinkBranding200","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.","enum":[true,false],"refName":"Default2","modelName":"Default2"},"valid":{"type":"boolean","description":"Indicates if this link branding is valid.","enum":[true,false],"refName":"Valid3","modelName":"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.","enum":[true,false],"refName":"Legacy","modelName":"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.","enum":[true,false],"refName":"Valid4","modelName":"Valid4"},"type":{"type":"string","description":"The type of DNS record that was generated.","enum":["cname","txt","mx"],"refName":"Type","modelName":"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.","required":["valid","host","data"],"properties":{"valid":{"type":"boolean","description":"Indicates if the DNS record is valid.","enum":[true,false],"refName":"Valid5","modelName":"Valid5"},"type":{"type":"string","description":"The type of DNS record generated.","enum":["cname","txt","mx"],"refName":"Type1","modelName":"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."}}}}}}},"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"}}}}}}}}}] ``` Create a branded link ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const data = { domain: "example.com", subdomain: "mail", default: true, }; const request = { url: `/v3/whitelabel/links`, method: "POST", 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")) data = {"domain": "example.com", "subdomain": "mail", "default": True} response = sg.client.whitelabel.links.post(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 data = @"{ ""domain"": ""example.com"", ""subdomain"": ""mail"", ""default"": true }"; var response = await client.RequestAsync( method: SendGridClient.Method.POST, urlPath: "whitelabel/links", 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.POST); request.setEndpoint("/whitelabel/links"); request.setBody(new JSONObject(new HashMap() { { put("domain", "example.com"); put("subdomain", "mail"); put("default", true); } }).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/whitelabel/links", host) request.Method = "POST" request.Body = []byte(`{ "domain": "example.com", "subdomain": "mail", "default": true }`) 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 = $_ENV["SENDGRID_API_KEY"]; $sg = new \SendGrid($apiKey); $request_body = json_decode('{ "domain": "example.com", "subdomain": "mail", "default": true }'); try { $response = $sg->client->whitelabel()->links()->post($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('{ "domain": "example.com", "subdomain": "mail", "default": true }') response = sg.client.whitelabel.links.post(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X POST "https://api.sendgrid.com/v3/whitelabel/links" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"domain": "example.com", "subdomain": "mail", "default": true}' ```