# Associate an Authenticated Domain with a Subuser (for up to Five Domains) ## 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}/subuser:add","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 associate a specific authenticated domain with a subuser. It can be used to associate up to five authenticated domains.** This functionality allows subusers to send mail using their parent's domain. Authenticated domains can be associated with (i.e. assigned to) subusers from a parent account. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools. A subuser can have up to five associated authenticated domains. To see the domains that have already been associated with this user, you can [use the API to list the domains currently associated with the subuser](/docs/sendgrid/api-reference/domain-authentication/list-the-authenticated-domain-associated-with-a-subuser-multiple). When selecting a domain to send email from, SendGrid checks for domains in the following order and chooses the first one that appears in the hierarchy: 1. Domain assigned by the subuser that matches the email's `From` address domain. 2. The subuser's default domain. 3. Domain assigned by the parent user that matches the `From` address domain. 4. Parent user's default domain. 5. sendgrid.net ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}}] ``` ### Path parameters ```json [{"name":"domain_id","in":"path","description":"ID of the authenticated domain to associate with the subuser.","required":true,"schema":{"type":"integer"}}] ``` ### Request body ```json {"schema":{"type":"object","required":["username"],"example":{"username":"jdoe"},"properties":{"username":{"type":"string","description":"Username to associate with the authenticated domain."}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"201","schema":{"description":"","content":{"application/json":{"schema":{"title":"Domain Authentication","type":"object","required":["id","domain","username","user_id","ips","custom_spf","default","legacy","automatic_security","valid","dns"],"refName":"AuthenticatedDomainSpf","modelName":"AuthenticatedDomainSpf","properties":{"id":{"type":"integer","description":"The ID of the authenticated domain."},"domain":{"type":"string","description":"The domain authenticated."},"subdomain":{"type":"string","description":"The subdomain that was used to create this authenticated domain."},"username":{"type":"string","description":"The username of the account that this authenticated domain is associated with."},"user_id":{"type":"integer","description":"The user_id of the account that this authenticated domain is associated with."},"ips":{"type":"array","description":"The IP addresses that are included in the SPF record for this authenticated domain."},"custom_spf":{"type":"boolean","description":"Indicates if this authenticated domain uses custom SPF."},"default":{"type":"boolean","description":"Indicates if this is the default 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 for this authenticated domain.","required":["mail_server","subdomain_spf","domain_spf","dkim"],"properties":{"mail_server":{"type":"object","description":"Designates which mail server is responsible for accepting messages from a domain.","required":["host","type","data","valid"],"properties":{"host":{"type":"string","description":"The domain sending the messages."},"type":{"type":"string","description":"They type of DNS record."},"data":{"type":"string","description":"The mail server responsible for accepting messages from the sending domain."},"valid":{"type":"boolean","description":"Indicates if this is a valid DNS record."}}},"subdomain_spf":{"type":"object","description":"The SPF record for the subdomain used to create this authenticated domain.","required":["host","type","data","valid"],"properties":{"host":{"type":"string","description":"The domain that this SPF record will be used to authenticate."},"type":{"type":"string","description":"The type of data in the SPF record."},"data":{"type":"string","description":"The SPF record."},"valid":{"type":"boolean","description":"Indicates if this is a valid SPF record."}}},"domain_spf":{"type":"object","description":"The SPF record for the root domain.","required":["host","type","data","valid"],"properties":{"host":{"type":"string","description":"The root domain that this SPF record will be used to authenticate."},"type":{"type":"string","description":"The type of data in the SPF record."},"data":{"type":"string","description":"The SPF record."},"valid":{"type":"boolean","description":"Indicates if the SPF record is valid."}}},"dkim":{"type":"object","description":"The DKIM record for messages sent using this authenticated domain.","required":["host","type","data","valid"],"properties":{"host":{"type":"string","description":"The DNS labels for the DKIM signature."},"type":{"type":"string","description":"The type of data in the DKIM record."},"data":{"type":"string","description":"The DKIM record."},"valid":{"type":"boolean","description":"Indicates if the DKIM record is valid."}}}}}}},"examples":{"response":{"value":{"id":1,"domain":"example.com","subdomain":"mail","username":"jdoe","user_id":7,"ips":[],"custom_spf":true,"default":false,"legacy":false,"automatic_security":false,"valid":false,"dns":{"mail_server":{"host":"mail.example.com","type":"mx","data":"sendgrid.net","valid":false},"subdomain_spf":{"host":"mail.example.com","type":"txt","data":"v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all","valid":false},"domain_spf":{"host":"example.com","type":"txt","data":"v=spf1 include:mail.example.com -all","valid":false},"dkim":{"host":"s1._domainkey.example.com","type":"txt","data":"k=rsa; t=s; p=publicKey","valid":false}}}}}}}}}] ``` Associate an authenticated domain with a subuser, for up to five domains ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const domain_id = 42; const data = { username: "jdoe", }; const request = { url: `/v3/whitelabel/domains/${domain_id}/subuser:add`, 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")) domain_id = 42 data = {"username": "jdoe"} response = sg.client._(f"whitelabel/domains/{domain_id}/subuser:add").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 domainId = 42; var data = @"{ ""username"": ""jdoe"" }"; var response = await client.RequestAsync( method: SendGridClient.Method.POST, urlPath: $"whitelabel/domains/{domainId}/subuser:add", 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.POST); request.setEndpoint("/whitelabel/domains/42/subuser:add"); request.setBody(new JSONObject(new HashMap() { { put("username", "jdoe"); } }).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/42/subuser:add", host) request.Method = "POST" request.Body = []byte(`{ "username": "jdoe" }`) 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('{ "username": "jdoe" }'); $domain_id = 42; try { $response = $sg->client ->_("whitelabel/domains/{$domain_id}/subuser:add") ->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('{ "username": "jdoe" }') domain_id = 42 response = sg.client._("whitelabel/domains/#{domain_id}/subuser:add").post(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X POST "https://api.sendgrid.com/v3/whitelabel/domains/42/subuser:add" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"username": "jdoe"}' ```