# Update an authenticated domain ## API Overview An authenticated domain allows you to remove the "via" or "sent on behalf of" message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will get 2 TXT records and 1 MX record. Domain Authentication was formerly called "Domain Whitelabel". For more information, please see [How to set up domain authentication](/docs/sendgrid/ui/account-and-settings/how-to-set-up-domain-authentication/). > \[!NOTE] > > Each user may have a maximum of 3,000 authenticated domains and 3,000 link brandings. This limit is at the user level, meaning each Subuser belonging to a parent account may have its own 3,000 authenticated domains and 3,000 link brandings. ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/whitelabel/domains/{domain_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 allows you to update the settings for an authenticated domain.** ## 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**](/docs/sendgrid/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"}] ``` ### Path parameters ```json [{"name":"domain_id","in":"path","required":true,"schema":{"type":"string"}}] ``` ### Request body ```json {"schema":{"type":"object","example":{"default":false,"custom_spf":true},"properties":{"default":{"type":"boolean","default":false,"description":"Indicates whether this is the default authenticated domain."},"custom_spf":{"type":"boolean","default":false,"description":"Indicates whether to generate a custom SPF record for manual security."}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"200","schema":{"description":"Success response","content":{"application/json":{"schema":{"type":"array","example":[{"id":1,"user_id":7,"subdomain":"mail","domain":"example.com","username":"jane@example.com","ips":["192.168.1.1","192.168.1.2"],"custom_spf":true,"default":true,"legacy":false,"automatic_security":true,"valid":true,"dns":{"mail_cname":{"valid":true,"type":"cname","host":"mail.example.com","data":"u7.wl.sendgrid.net"},"dkim1":{"valid":true,"type":"cname","host":"s1._domainkey.example.com","data":"s1._domainkey.u7.wl.sendgrid.net"},"dkim2":{"valid":true,"type":"cname","host":"s2._domainkey.example.com","data":"s2._domainkey.u7.wl.sendgrid.net"}}},{"id":2,"user_id":8,"subdomain":"new","domain":"example2.com","username":"john@example2.com","ips":[],"custom_spf":false,"default":true,"legacy":false,"automatic_security":true,"valid":false,"dns":{"mail_cname":{"valid":false,"type":"mx","host":"news.example2.com","data":"sendgrid.net"},"dkim1":{"valid":false,"type":"txt","host":"example2.com","data":"k=rsa; t=s; p=publicKey"},"dkim2":{"valid":false,"type":"txt","host":"example2.com","data":"k=rsa; t=s p=publicKey"}}}],"items":{"type":"object","required":["automatic_security","custom_spf","default","dns","domain","id","ips","legacy","subdomain","user_id","username","valid"],"properties":{"id":{"type":"number","description":"The ID of the authenticated domain."},"user_id":{"type":"number","description":"The ID of the user that this domain is associated with."},"subdomain":{"type":"string","description":"The subdomain or custom return-path to use for this authenticated domain."},"domain":{"type":"string","description":"The domain to be authenticated."},"username":{"type":"string","description":"The username that this domain will be associated with."},"ips":{"type":"array","description":"The IPs to be included in the custom SPF record for this authenticated domain.","items":{"type":"string"}},"custom_spf":{"type":"boolean","description":"Indicates whether this authenticated domain uses custom SPF."},"default":{"type":"boolean","description":"Indicates if this is the default authenticated domain."},"legacy":{"type":"boolean","description":"Indicates if this authenticated domain was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create a new authenticated domain if you need to update it."},"automatic_security":{"type":"boolean","description":"Indicates if this authenticated domain uses automated security."},"valid":{"type":"boolean","description":"Indicates if this is a valid authenticated domain."},"dns":{"type":"object","description":"The DNS records used to authenticate the sending domain.","required":["mail_cname","dkim1","dkim2"],"properties":{"mail_cname":{"type":"object","description":"The CNAME for your sending domain that points to sendgrid.net.","required":["valid","type","host","data"],"properties":{"valid":{"type":"boolean","description":"Indicates if this is a valid CNAME."},"type":{"type":"string","description":"The type of DNS record."},"host":{"type":"string","description":"The domain that this CNAME is created for.","format":"hostname"},"data":{"type":"string","description":"The CNAME record."}}},"dkim1":{"type":"object","description":"A DNS record.","required":["valid","type","host","data"],"properties":{"valid":{"type":"boolean","description":"Indicates if this is a valid DNS record."},"type":{"type":"string","description":"The type of DNS record."},"host":{"type":"string","description":"The domain that this DNS record was created for."},"data":{"type":"string","description":"The DNS record."}}},"dkim2":{"type":"object","description":"A DNS record.","required":["valid","type","host","data"],"properties":{"valid":{"type":"boolean","description":"Indicates if this is a valid DNS record."},"type":{"type":"string","description":"The type of DNS record."},"host":{"type":"string","description":"The domain that this DNS record was created for."},"data":{"type":"string","description":"The DNS record."}}}}},"subusers":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer","description":"The ID of the subuser that this authenticated domain will be associated with."},"username":{"type":"string","description":"The username of the subuser that this authenticated domain is associated with."}}}},"last_validation_attempt_at":{"type":"integer","description":"A Unix epoch timestamp representing the last time of a validation attempt."}}}},"examples":{"response":{"value":[{"id":1,"user_id":7,"subdomain":"mail","domain":"example.com","username":"jane@example.com","ips":["192.168.1.1","192.168.1.2"],"custom_spf":true,"default":true,"legacy":false,"automatic_security":true,"valid":true,"dns":{"mail_cname":{"valid":true,"type":"cname","host":"mail.example.com","data":"u7.wl.sendgrid.net"},"dkim1":{"valid":true,"type":"cname","host":"s1._domainkey.example.com","data":"s1._domainkey.u7.wl.sendgrid.net"},"dkim2":{"valid":true,"type":"cname","host":"s2._domainkey.example.com","data":"s2._domainkey.u7.wl.sendgrid.net"}}},{"id":2,"user_id":8,"subdomain":"new","domain":"example2.com","username":"john@example2.com","ips":[],"custom_spf":false,"default":true,"legacy":false,"automatic_security":true,"valid":false,"dns":{"mail_cname":{"valid":false,"type":"mx","host":"news.example2.com","data":"sendgrid.net"},"dkim1":{"valid":false,"type":"txt","host":"example2.com","data":"k=rsa; t=s; p=publicKey"},"dkim2":{"valid":false,"type":"txt","host":"example2.com","data":"k=rsa; t=s p=publicKey"}}}]}}}},"refName":"#/components/responses/DomainAuthentication200","modelName":"__components_responses_DomainAuthentication200"}}] ``` Update an authenticated domain ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const domain_id = "domain_id"; const data = { default: false, custom_spf: true, }; const request = { url: `/v3/whitelabel/domains/${domain_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")) domain_id = "domain_id" data = {"default": False, "custom_spf": True} response = sg.client.whitelabel.domains._(domain_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 domainId = "domain_id"; var data = @"{ ""default"": false, ""custom_spf"": true }"; var response = await client.RequestAsync( method: SendGridClient.Method.PATCH, urlPath: $"whitelabel/domains/{domainId}", 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; 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("/whitelabel/domains/domain_id"); request.setBody(new JSONObject(new HashMap() { { put("default", false); put("custom_spf", 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/domains/domain_id", host) request.Method = "PATCH" request.Body = []byte(`{ "default": false, "custom_spf": 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 = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('{ "default": false, "custom_spf": true }'); $domain_id = "domain_id"; try { $response = $sg->client ->whitelabel() ->domains() ->_($domain_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('{ "default": false, "custom_spf": true }') domain_id = "domain_id" response = sg.client.whitelabel.domains._(domain_id).patch(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X PATCH "https://api.sendgrid.com/v3/whitelabel/domains/domain_id" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"default": false, "custom_spf": true}' ```