{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Domain Authentication API", "summary": "The Twilio SendGrid Domain Authentication API allows you to manage your authenticated domains and their settings.", "description": "The Twilio SendGrid Domain Authentication API allows you to manage your authenticated domains and their settings.\n\nDomain Authentication is a required step when setting up your Twilio SendGrid account because it's essential to ensuring the deliverability of your email. Domain Authentication signals trustworthiness to email inbox providers and your recipients by approving SendGrid to send email on behalf of your domain. For more information, see [**How to Set Up Domain Authentication**](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/).\n\nEach 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.", "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": "domain_authentication" } }, "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/dns/email": { "post": { "operationId": "EmailDnsRecord", "summary": "Email DNS records to a co-worker", "tags": [ "Domain Authentication" ], "description": "**This endpoint is used to share DNS records with a colleagues**\n\nUse this endpoint to send SendGrid-generated DNS record information to a co-worker so they can enter it into your DNS provider to validate your domain and link branding. \n\nWhat type of records are sent will depend on whether you have chosen Automated Security or not. When using Automated Security, SendGrid provides you with three CNAME records. If you turn Automated Security off, you are instead given TXT and MX records.\n\nIf you pass a `link_id` to this endpoint, the generated email will supply the DNS records necessary to complete [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setup. If you pass a `domain_id` to this endpoint, the generated email will supply the DNS records needed to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/). Passing both IDs will generate an email with the records needed to complete both setup steps.\n\nYou can retrieve all your domain IDs from the returned `id` fields for each domain using the \"List all authenticated domains\" endpoint. You can retrieve all of your link IDs using the \"Retrieve all branded links\" endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "link_id": { "type": "integer", "minimum": 0, "description": "The ID of the branded link." }, "domain_id": { "type": "integer", "minimum": 0, "description": "The ID of your SendGrid domain record." }, "email": { "type": "string", "format": "email", "description": "The email address to send the DNS information to." }, "message": { "type": "string", "default": "Please set these DNS records in our hosting solution.", "description": "A custom text block to include in the email body sent with the records." } }, "required": [ "link_id", "domain_id", "email" ], "example": { "link_id": 29719392, "domain_id": 46873408, "email": "my_colleague@example.com", "message": "DNS Record for verification" } } } } }, "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "error": { "type": "string" }, "field": { "type": "string" } } } } } } } } } } }, "/v3/whitelabel/domains": { "get": { "operationId": "ListAuthenticatedDomain", "summary": "List all authenticated domains", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve a paginated list of all domains you have authenticated.**\n\nYou can use the `limit` query parameter to set the page size. If your list contains more items than the page size permits, you can make multiple requests. Use the `offset` query parameter to control the position in the list from which to start retrieving additional items.", "parameters": [ { "name": "limit", "in": "query", "description": "`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/PaginationCommonOffset" }, { "name": "exclude_subusers", "in": "query", "description": "Exclude subuser domains from the result.", "schema": { "type": "boolean" } }, { "name": "username", "in": "query", "description": "The username associated with an authenticated domain.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Search for authenticated domains.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "$ref": "#/components/responses/DomainAuthentication200" } } }, "post": { "operationId": "AuthenticateDomain", "summary": "Authenticate a domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to authenticate a domain.**\n\nIf you are authenticating a domain for a subuser, you have two options:\n1. Use the \"username\" parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain.\n2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain being authenticated." }, "subdomain": { "type": "string", "description": "The subdomain or custom return-path to use for this authenticated domain." }, "username": { "type": "string", "description": "The username associated with this domain." }, "ips": { "type": "array", "description": "The IP addresses that will be included in the custom SPF record for this authenticated domain.", "items": { "type": "string" } }, "custom_spf": { "type": "boolean", "description": "Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to authenticated domains set up for manual security." }, "default": { "type": "boolean", "description": "Whether to use this authenticated domain as the fallback if no authenticated domains match the sender's domain." }, "automatic_security": { "type": "boolean", "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation." }, "custom_dkim_selector": { "type": "string", "description": "Add a custom DKIM selector. Accepts three letters or numbers." }, "region": { "type": "string", "description": "The region of the domain. Allowed values are `global` and `eu`. The default value is `global`." } }, "required": [ "domain" ], "example": { "domain": "example.com", "subdomain": "news", "username": "john@example.com", "ips": [ "192.168.1.1", "192.168.1.2" ], "custom_spf": true, "default": true, "automatic_security": false, "custom_dkim_selector": "string", "region": "global" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedDomain" }, "examples": { "response": { "value": { "id": 302183, "user_id": 1446226, "subdomain": "example", "domain": "example.com", "username": "mbernier", "ips": [], "custom_spf": false, "default": true, "legacy": false, "automatic_security": true, "valid": false, "dns": { "mail_cname": { "valid": false, "type": "cname", "host": "example.example.com", "data": "u1446226.wl.sendgrid.net" }, "dkim1": { "valid": false, "type": "cname", "host": "s1._domainkey.example.com", "data": "s1.domainkey.u1446226.wl.sendgrid.net" }, "dkim2": { "valid": false, "type": "cname", "host": "s2._domainkey.example.com", "data": "s2.domainkey.u1446226.wl.sendgrid.net" } } } } } } } } } } }, "/v3/whitelabel/domains/{domain_id}": { "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetAuthenticatedDomain", "summary": "Retrieve an authenticated domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve a specific authenticated domain.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedDomain" }, "examples": { "response": { "value": { "id": 45373692, "user_id": 66036447, "subdomain": "sub", "domain": "example.com", "username": "jdoe", "ips": [ "127.0.0.1" ], "custom_spf": false, "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" } } } } } } } } } }, "patch": { "operationId": "UpdateAuthenticatedDomain", "summary": "Update an authenticated domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to update the settings for an authenticated domain.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "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." } }, "example": { "default": false, "custom_spf": true } } } } }, "responses": { "200": { "$ref": "#/components/responses/DomainAuthentication200" } } }, "delete": { "operationId": "DeleteAuthenticatedDomain", "summary": "Delete an authenticated domain.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to delete an authenticated domain.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" } } } }, "/v3/whitelabel/domains/{domain_id}/subuser": { "post": { "operationId": "AssociateSubuserWithDomain", "summary": "Associate an authenticated domain with a given user.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to associate a specific authenticated domain with a subuser.**\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain. 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.\n\n\n[You can associate more than one domain with a subuser using the `v3/whitelabel/domains/{domain_id}/subuser:add` endpoint](https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/associate-an-authenticated-domain-with-a-subuser-multiple).", "parameters": [ { "name": "domain_id", "in": "path", "description": "ID of the authenticated domain to associate with the subuser.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Username to associate with the authenticated domain." } }, "required": [ "username" ], "example": { "username": "jdoe" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedDomainSpf" }, "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 } } } } } } } } } }, "delete": { "operationId": "DisassociateSubuserFromDomain", "summary": "Disassociate an authenticated domain from a given user for users with up to five associated domains.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to disassociate a specific authenticated domain from a subuser, for users with up to five associated domains.**\n\n\nThis functionality allows subusers to send mail using their parent's domain. Authenticated domains can be associated with (i.e. assigned to) subusers kknt, and a subuser can have up to five associated authenticated domains. \n\nYou can dissociate an authenticated domain from any subuser that has one or more authenticated domains using this endpoint.", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domain.", "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "description": "ID of the authenticated domain to be disassociated with the subuser.", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "" } } } }, "/v3/whitelabel/domains/{domain_id}/subuser:add": { "parameters": [ { "name": "domain_id", "in": "path", "description": "ID of the authenticated domain to associate with the subuser.", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "AssociateSubuserWithDomainMultiple", "summary": "Associate an authenticated domain with a given user, for up to five domains.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to associate a specific authenticated domain with a subuser. It can be used to associate up to five authenticated domains.**\n\n\nThis 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.\n\n\nA 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](https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/list-the-authenticated-domain-associated-with-a-subuser-multiple).\n\n\nWhen 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: \n1. Domain assigned by the subuser that matches the email's `From` address domain. \n2. The subuser's default domain. \n3. Domain assigned by the parent user that matches the `From` address domain. \n4. Parent user's default domain. \n5. sendgrid.net", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Username to associate with the authenticated domain." } }, "required": [ "username" ], "example": { "username": "jdoe" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedDomainSpf" }, "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 } } } } } } } } } } }, "/v3/whitelabel/domains/{id}/ips": { "parameters": [ { "name": "id", "in": "path", "description": "ID of the domain to which you are adding an IP", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "AddIpToAuthenticatedDomain", "summary": "Add an IP to an authenticated domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to add an IP address to an authenticated domain.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." } }, "required": [ "ip" ], "example": { "ip": "192.168.0.1" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedDomainSpf" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "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 } } } } } } } } } } }, "/v3/whitelabel/domains/{id}/ips/{ip}": { "parameters": [ { "name": "id", "in": "path", "description": "ID of the domain to delete the IP from.", "required": true, "schema": { "type": "integer" } }, { "name": "ip", "in": "path", "description": "IP to remove from the domain.", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "DeleteIpFromAuthenticatedDomain", "summary": "Remove an IP from an authenticated domain.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to remove an IP address from that domain's authentication.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedDomainSpf" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "mail@example.com", "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 } } } } } } } } } } }, "/v3/whitelabel/domains/{id}/validate": { "parameters": [ { "name": "id", "in": "path", "description": "ID of the domain to validate.", "required": true, "schema": { "type": "integer" } } ], "post": { "operationId": "ValidateAuthenticatedDomain", "summary": "Validate a domain authentication.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to validate an authenticated domain. If it fails, it will return an error message describing why the domain could not be validated.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the authenticated domain." }, "valid": { "type": "boolean", "description": "Indicates if this is a valid authenticated domain." }, "validation_results": { "type": "object", "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", "properties": { "mail_cname": { "type": "object", "description": "The CNAME record for the authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if this DNS record is valid." }, "reason": { "description": "The reason this record is invalid.", "nullable": true, "type": "string" } } }, "dkim1": { "type": "object", "description": "A DNS record for this authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid." }, "reason": { "nullable": true, "type": "string" } } }, "dkim2": { "type": "object", "description": "A DNS record for this authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid." }, "reason": { "nullable": true, "type": "string" } } }, "spf": { "type": "object", "description": "The SPF record for the authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the SPF record is valid." }, "reason": { "nullable": true, "type": "string" } } } } } } }, "examples": { "response": { "value": { "id": 1, "valid": true, "validation_results": { "mail_cname": { "valid": false, "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\"." }, "dkim1": { "valid": true, "reason": null }, "dkim2": { "valid": true, "reason": null }, "spf": { "valid": true, "reason": null } } } } } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "A message explaining the reason for the error." } }, "required": [ "message" ] } } } }, "examples": { "response": { "value": { "errors": [ { "message": "internal error getting TXT" } ] } } } } } } } } }, "/v3/whitelabel/domains/default": { "get": { "operationId": "ListDefaultAuthenticatedDomain", "summary": "Get the default authentication", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve the default authentication for a domain.**\n\nWhen creating or updating a domain authentication, you can set the domain as a default. The default domain will be used to send all mail. If you have multiple authenticated domains, the authenticated domain matching the domain of the From address will be used, and the default will be overridden.\n\nThis endpoint will return a default domain and its details only if a default is set. You are not required to set a default. If you do not set a default domain, this endpoint will return general information about your domain authentication status.", "parameters": [ { "name": "domain", "in": "query", "description": "The domain to find a default authentication.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "$ref": "#/components/responses/DomainAuthentication200" } } } }, "/v3/whitelabel/domains/subuser": { "get": { "operationId": "ListAuthenticatedDomainWithUser", "summary": "List the authenticated domain associated with the given user.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve all of the authenticated domains that have been assigned to a specific subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain. 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.\n\n\nNote that if you used the [`/v3/whitelabel/domains/{domain_id}/subuser:add` endpoint]( https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/associate-an-authenticated-domain-with-a-subuser-multiple) to add multiple domains to the subuser, you can use the [`/v3/whitelabel/domains/subuser/all` endpoint](https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/list-the-authenticated-domain-associated-with-a-subuser-multiple) to list those associated domains.", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domain.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedDomainSpf" }, "examples": { "response": { "value": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "mail@example.com", "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 } } } } } } } } } }, "delete": { "operationId": "DisassociateAuthenticatedDomainFromUser", "summary": "Disassociate an authenticated domain from a given user.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to disassociate a specific authenticated domain from a subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain. 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.\n\n\nNote that if you used the [`/v3/whitelabel/domains/{domain_id}/subuser:add` endpoint](https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/associate-an-authenticated-domain-with-a-subuser-multiple) to add multiple domains to the subuser, you should use the [`/v3/whitelabel/domains/{domain_id}/subuser` endpoint](https://www.twilio.com/docs/sendgrid/api-reference/domain-authentication/disassociate-an-authenticated-domain-from-a-subuser-multiple) to disassociate those domains.", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domain.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" } } } }, "/v3/whitelabel/domains/subuser/all": { "get": { "operationId": "ListAllAuthenticatedDomainWithUser", "summary": "List all the authenticated domains associated with the given user.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve all of the authenticated domains that have been assigned to a specific subuser.**\n\n\nThis 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, and a subuser can have up to five associated domains. \n\nTo 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.\n\n\nWhen 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: \n1. Domain assigned by the subuser that matches the email's `From` address domain. \n2. The subuser's default domain. \n3. Domain assigned by the parent user that matches the `From` address domain. \n4. Parent user's default domain. \n5. sendgrid.net", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domains.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "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." } } } } } }, "required": [ "automatic_security", "custom_spf", "default", "dns", "domain", "id", "ips", "legacy", "subdomain", "user_id", "username", "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_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, "domain": "example.com", "subdomain": "mail2", "username": "jdoe2", "user_id": 7, "ips": [], "custom_spf": true, "default": true, "legacy": false, "automatic_security": true, "valid": false, "dns": { "mail_cname": { "valid": true, "type": "cname", "host": "mail2.example2.com", "data": "u7.sgsandbox.net" }, "dkim1": { "host": "s1._domainkey.example.com", "type": "cname", "data": "s1._domainkey.u7.wl.sgsandbox.net", "valid": true }, "dkim2": { "valid": true, "type": "cname", "host": "s2._domainkey.example2.com", "data": "s2._domainkey.u7.w1.sgsandbox.net" } } } ] } } } } } } } } }, "components": { "schemas": { "AuthenticatedDomain": { "title": "Domain Authentication - Mandatory Subdomain", "type": "object", "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." } } } } } }, "required": [ "id", "user_id", "subdomain", "domain", "username", "ips", "custom_spf", "default", "legacy", "automatic_security", "valid", "dns" ], "example": { "id": 45373692, "user_id": 66036447, "subdomain": "sub", "domain": "example.com", "username": "jdoe", "ips": [ "127.0.0.1" ], "custom_spf": false, "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" } } } }, "AuthenticatedDomainSpf": { "title": "Domain Authentication", "type": "object", "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.", "items": {} }, "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." } } } } } }, "required": [ "id", "domain", "username", "user_id", "ips", "custom_spf", "default", "legacy", "automatic_security", "valid", "dns" ] } }, "responses": { "DomainAuthentication200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "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." } }, "required": [ "automatic_security", "custom_spf", "default", "dns", "domain", "id", "ips", "legacy", "subdomain", "user_id", "username", "valid" ] }, "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" } } } ] }, "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" } } } ] } } } } } }, "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" } }, "PaginationCommonOffset": { "name": "offset", "in": "query", "required": false, "description": "The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "examples": {}, "requestBodies": {}, "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": "Domain Authentication", "description": "Twilio SendGrid Domain Authentication API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }