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. Domain 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/). 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.' 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.** You 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.** If you are authenticating a domain for a subuser, you have two options: 1. 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. 2. 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.** Authenticated 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. [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_resuts: 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.** When 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. This 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.** Authenticated 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. Note 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.** Authenticated 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. Note 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