# Domains
Configure and verify domains for email sending to ensure deliverability.
## List domains
> Get all domains and their verification status
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"responses":{"DomainsResponse":{"description":"List of domains","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"integer"},"domain_name":{"type":"string"},"demo":{"type":"boolean"},"compliance_status":{"type":"string","description":"Indicates the compliance verification status of the domain.\nThe domain must reach `compliant` status before you can send emails\nin production.\n\n- `demo` - A demo domain provided by Mailtrap. Can only send emails to the account owner.\n- `demo_exhausted` - A demo domain that has used up its sending allowance. Cannot send emails.\n- `unverified_dns` - Domain DNS records have not been verified yet. Open your domain on the [Domains](https://mailtrap.io/domains) page and follow the [Sending Domain Setup](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain) guide.\n- `missing_company_info` - Account is missing required company information. Go to [Company Information](https://mailtrap.io/settings/account?current_tab=company_information) and fill in the required details.\n- `under_review` - Domain is undergoing automatic compliance review. No action needed — typically completes within 2 minutes.\n- `awaiting_questionnaire` - Automatic review required additional information. Open your domain on the [Domains](https://mailtrap.io/domains) page and fill in the compliance questionnaire.\n- `awaiting_card_verification` - Compliance questionnaire was submitted but credit card identity verification is still needed. Open your domain on the [Domains](https://mailtrap.io/domains) page and enter card details. The charged amount is refunded immediately and the card is not stored.\n- `non_compliant` - Domain did not pass compliance checks. Sending is not allowed. Contact [Mailtrap Support](mailto:support@mailtrap.io) for details and next steps.\n- `compliant` - Domain has passed all compliance checks and is ready to send emails.\n- `suspended` - Domain sending has been suspended. Contact [Mailtrap Support](mailto:support@mailtrap.io) to resolve the issue.\n","enum":["demo","demo_exhausted","unverified_dns","missing_company_info","under_review","awaiting_questionnaire","awaiting_card_verification","non_compliant","compliant","suspended"]},"dns_verified":{"type":"boolean"},"dns_verified_at":{"type":["string","null"]},"dns_records":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unchecked","missing","softfail","network_error"]},"type":{"type":"string"},"value":{"type":"string"}}}},"open_tracking_enabled":{"type":"boolean"},"click_tracking_enabled":{"type":"boolean"},"auto_unsubscribe_link_enabled":{"type":"boolean"},"custom_domain_tracking_enabled":{"type":"boolean"},"health_alerts_enabled":{"type":"boolean"},"critical_alerts_enabled":{"type":"boolean"},"alert_recipient_email":{"type":["string","null"]},"permissions":{"type":"object","properties":{"can_read":{"type":"boolean"},"can_update":{"type":"boolean"},"can_destroy":{"type":"boolean"}}}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}}}},"paths":{"/api/domains":{"get":{"summary":"List domains","description":"Get all domains and their verification status","operationId":"getDomains","tags":["domains"],"responses":{"200":{"$ref":"#/components/responses/DomainsResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```
## Create domain
> Create a domain for email authentication. After creation, verify the domain by adding DNS records.\
> \
> \*\*Process:\*\*\
> 1\. Create the domain\
> 2\. Add DNS records (SPF, DKIM, DMARC)\
> 3\. Verify the records\
> 4\. Start sending emails
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"responses":{"DomainResponse":{"description":"Domain details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"UnprocessableEntity":{"description":"Validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"integer"},"domain_name":{"type":"string"},"demo":{"type":"boolean"},"compliance_status":{"type":"string","description":"Indicates the compliance verification status of the domain.\nThe domain must reach `compliant` status before you can send emails\nin production.\n\n- `demo` - A demo domain provided by Mailtrap. Can only send emails to the account owner.\n- `demo_exhausted` - A demo domain that has used up its sending allowance. Cannot send emails.\n- `unverified_dns` - Domain DNS records have not been verified yet. Open your domain on the [Domains](https://mailtrap.io/domains) page and follow the [Sending Domain Setup](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain) guide.\n- `missing_company_info` - Account is missing required company information. Go to [Company Information](https://mailtrap.io/settings/account?current_tab=company_information) and fill in the required details.\n- `under_review` - Domain is undergoing automatic compliance review. No action needed — typically completes within 2 minutes.\n- `awaiting_questionnaire` - Automatic review required additional information. Open your domain on the [Domains](https://mailtrap.io/domains) page and fill in the compliance questionnaire.\n- `awaiting_card_verification` - Compliance questionnaire was submitted but credit card identity verification is still needed. Open your domain on the [Domains](https://mailtrap.io/domains) page and enter card details. The charged amount is refunded immediately and the card is not stored.\n- `non_compliant` - Domain did not pass compliance checks. Sending is not allowed. Contact [Mailtrap Support](mailto:support@mailtrap.io) for details and next steps.\n- `compliant` - Domain has passed all compliance checks and is ready to send emails.\n- `suspended` - Domain sending has been suspended. Contact [Mailtrap Support](mailto:support@mailtrap.io) to resolve the issue.\n","enum":["demo","demo_exhausted","unverified_dns","missing_company_info","under_review","awaiting_questionnaire","awaiting_card_verification","non_compliant","compliant","suspended"]},"dns_verified":{"type":"boolean"},"dns_verified_at":{"type":["string","null"]},"dns_records":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unchecked","missing","softfail","network_error"]},"type":{"type":"string"},"value":{"type":"string"}}}},"open_tracking_enabled":{"type":"boolean"},"click_tracking_enabled":{"type":"boolean"},"auto_unsubscribe_link_enabled":{"type":"boolean"},"custom_domain_tracking_enabled":{"type":"boolean"},"health_alerts_enabled":{"type":"boolean"},"critical_alerts_enabled":{"type":"boolean"},"alert_recipient_email":{"type":["string","null"]},"permissions":{"type":"object","properties":{"can_read":{"type":"boolean"},"can_update":{"type":"boolean"},"can_destroy":{"type":"boolean"}}}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"type":"object","description":"Validation errors per field. Keys are attribute names; values are arrays of human-readable messages.\nSome endpoints may also return a `base` key with general validation errors.","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/domains":{"post":{"summary":"Create domain","description":"Create a domain for email authentication. After creation, verify the domain by adding DNS records.\n\n**Process:**\n1. Create the domain\n2. Add DNS records (SPF, DKIM, DMARC)\n3. Verify the records\n4. Start sending emails\n","operationId":"createDomain","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"object","required":["domain_name"],"properties":{"domain_name":{"type":"string","format":"hostname","description":"Your domain name"}}}}}}}},"responses":{"200":{"$ref":"#/components/responses/DomainResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
## Get domain
> Get details and verification status of a specific domain
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"domain_id":{"name":"domain_id","in":"path","required":true,"description":"Domain ID","schema":{"type":"integer"}}},"responses":{"DomainResponse":{"description":"Domain details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"integer"},"domain_name":{"type":"string"},"demo":{"type":"boolean"},"compliance_status":{"type":"string","description":"Indicates the compliance verification status of the domain.\nThe domain must reach `compliant` status before you can send emails\nin production.\n\n- `demo` - A demo domain provided by Mailtrap. Can only send emails to the account owner.\n- `demo_exhausted` - A demo domain that has used up its sending allowance. Cannot send emails.\n- `unverified_dns` - Domain DNS records have not been verified yet. Open your domain on the [Domains](https://mailtrap.io/domains) page and follow the [Sending Domain Setup](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain) guide.\n- `missing_company_info` - Account is missing required company information. Go to [Company Information](https://mailtrap.io/settings/account?current_tab=company_information) and fill in the required details.\n- `under_review` - Domain is undergoing automatic compliance review. No action needed — typically completes within 2 minutes.\n- `awaiting_questionnaire` - Automatic review required additional information. Open your domain on the [Domains](https://mailtrap.io/domains) page and fill in the compliance questionnaire.\n- `awaiting_card_verification` - Compliance questionnaire was submitted but credit card identity verification is still needed. Open your domain on the [Domains](https://mailtrap.io/domains) page and enter card details. The charged amount is refunded immediately and the card is not stored.\n- `non_compliant` - Domain did not pass compliance checks. Sending is not allowed. Contact [Mailtrap Support](mailto:support@mailtrap.io) for details and next steps.\n- `compliant` - Domain has passed all compliance checks and is ready to send emails.\n- `suspended` - Domain sending has been suspended. Contact [Mailtrap Support](mailto:support@mailtrap.io) to resolve the issue.\n","enum":["demo","demo_exhausted","unverified_dns","missing_company_info","under_review","awaiting_questionnaire","awaiting_card_verification","non_compliant","compliant","suspended"]},"dns_verified":{"type":"boolean"},"dns_verified_at":{"type":["string","null"]},"dns_records":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unchecked","missing","softfail","network_error"]},"type":{"type":"string"},"value":{"type":"string"}}}},"open_tracking_enabled":{"type":"boolean"},"click_tracking_enabled":{"type":"boolean"},"auto_unsubscribe_link_enabled":{"type":"boolean"},"custom_domain_tracking_enabled":{"type":"boolean"},"health_alerts_enabled":{"type":"boolean"},"critical_alerts_enabled":{"type":"boolean"},"alert_recipient_email":{"type":["string","null"]},"permissions":{"type":"object","properties":{"can_read":{"type":"boolean"},"can_update":{"type":"boolean"},"can_destroy":{"type":"boolean"}}}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}},"paths":{"/api/domains/{domain_id}":{"get":{"summary":"Get domain","description":"Get details and verification status of a specific domain","operationId":"getDomain","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/domain_id"}],"responses":{"200":{"$ref":"#/components/responses/DomainResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Delete domain
> Remove a domain from your account
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"domain_id":{"name":"domain_id","in":"path","required":true,"description":"Domain ID","schema":{"type":"integer"}}},"responses":{"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}},"schemas":{"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}},"paths":{"/api/domains/{domain_id}":{"delete":{"summary":"Delete domain","description":"Remove a domain from your account","operationId":"deleteDomain","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/domain_id"}],"responses":{"204":{"description":"Domain successfully deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Update domain
> Update configuration settings for a domain.
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"domain_id":{"name":"domain_id","in":"path","required":true,"description":"Domain ID","schema":{"type":"integer"}}},"schemas":{"UpdateDomainRequest":{"type":"object","properties":{"open_tracking_enabled":{"type":"boolean","description":"Enable open tracking for emails sent from this domain"},"click_tracking_enabled":{"type":"boolean","description":"Enable click tracking for links in emails sent from this domain"},"auto_unsubscribe_link_enabled":{"type":"boolean","description":"Automatically add an unsubscribe link to emails sent from this domain"}}},"Domain":{"type":"object","properties":{"id":{"type":"integer"},"domain_name":{"type":"string"},"demo":{"type":"boolean"},"compliance_status":{"type":"string","description":"Indicates the compliance verification status of the domain.\nThe domain must reach `compliant` status before you can send emails\nin production.\n\n- `demo` - A demo domain provided by Mailtrap. Can only send emails to the account owner.\n- `demo_exhausted` - A demo domain that has used up its sending allowance. Cannot send emails.\n- `unverified_dns` - Domain DNS records have not been verified yet. Open your domain on the [Domains](https://mailtrap.io/domains) page and follow the [Sending Domain Setup](https://docs.mailtrap.io/email-api-smtp/setup/sending-domain) guide.\n- `missing_company_info` - Account is missing required company information. Go to [Company Information](https://mailtrap.io/settings/account?current_tab=company_information) and fill in the required details.\n- `under_review` - Domain is undergoing automatic compliance review. No action needed — typically completes within 2 minutes.\n- `awaiting_questionnaire` - Automatic review required additional information. Open your domain on the [Domains](https://mailtrap.io/domains) page and fill in the compliance questionnaire.\n- `awaiting_card_verification` - Compliance questionnaire was submitted but credit card identity verification is still needed. Open your domain on the [Domains](https://mailtrap.io/domains) page and enter card details. The charged amount is refunded immediately and the card is not stored.\n- `non_compliant` - Domain did not pass compliance checks. Sending is not allowed. Contact [Mailtrap Support](mailto:support@mailtrap.io) for details and next steps.\n- `compliant` - Domain has passed all compliance checks and is ready to send emails.\n- `suspended` - Domain sending has been suspended. Contact [Mailtrap Support](mailto:support@mailtrap.io) to resolve the issue.\n","enum":["demo","demo_exhausted","unverified_dns","missing_company_info","under_review","awaiting_questionnaire","awaiting_card_verification","non_compliant","compliant","suspended"]},"dns_verified":{"type":"boolean"},"dns_verified_at":{"type":["string","null"]},"dns_records":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pass","fail","unchecked","missing","softfail","network_error"]},"type":{"type":"string"},"value":{"type":"string"}}}},"open_tracking_enabled":{"type":"boolean"},"click_tracking_enabled":{"type":"boolean"},"auto_unsubscribe_link_enabled":{"type":"boolean"},"custom_domain_tracking_enabled":{"type":"boolean"},"health_alerts_enabled":{"type":"boolean"},"critical_alerts_enabled":{"type":"boolean"},"alert_recipient_email":{"type":["string","null"]},"permissions":{"type":"object","properties":{"can_read":{"type":"boolean"},"can_update":{"type":"boolean"},"can_destroy":{"type":"boolean"}}}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"type":"object","description":"Validation errors per field. Keys are attribute names; values are arrays of human-readable messages.\nSome endpoints may also return a `base` key with general validation errors.","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"DomainResponse":{"description":"Domain details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"UnprocessableEntity":{"description":"Validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}}},"paths":{"/api/domains/{domain_id}":{"patch":{"summary":"Update domain","description":"Update configuration settings for a domain.\n","operationId":"updateDomain","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/domain_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"$ref":"#/components/schemas/UpdateDomainRequest"}}}}}},"responses":{"200":{"$ref":"#/components/responses/DomainResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
## Send setup instructions
> Email DNS configuration instructions for the domain
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"domain_id":{"name":"domain_id","in":"path","required":true,"description":"Domain ID","schema":{"type":"integer"}}},"responses":{"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"UnprocessableEntity":{"description":"Validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}},"schemas":{"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"type":"object","description":"Validation errors per field. Keys are attribute names; values are arrays of human-readable messages.\nSome endpoints may also return a `base` key with general validation errors.","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/domains/{domain_id}/send_setup_instructions":{"post":{"summary":"Send setup instructions","description":"Email DNS configuration instructions for the domain","operationId":"sendDomainSetupInstructions","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/domain_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address to receive setup instructions"}}}}}},"responses":{"204":{"description":"Instructions sent successfully"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
## Get company info
> Get company information associated with a domain / account.
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"domain_id":{"name":"domain_id","in":"path","required":true,"description":"Domain ID","schema":{"type":"integer"}}},"responses":{"CompanyInfoResponse":{"description":"Company information","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyInfo"}}}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}},"schemas":{"CompanyInfo":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Company or individual name"},"address":{"type":["string","null"],"description":"Street address"},"city":{"type":["string","null"],"description":"City"},"country":{"type":["string","null"],"description":"Country"},"phone":{"type":["string","null"],"description":"Phone number"},"zip_code":{"type":["string","null"],"description":"ZIP or postal code"},"privacy_policy_url":{"type":["string","null"],"format":"uri","description":"URL to the privacy policy page"},"terms_of_service_url":{"type":["string","null"],"format":"uri","description":"URL to the terms of service page"},"website_url":{"type":["string","null"],"format":"uri","description":"Company website URL or LinkedIn / personal website"},"info_level":{"type":"string","enum":["business","individual"],"description":"Whether the sender is a business or individual"}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}},"paths":{"/api/domains/{domain_id}/company_info":{"get":{"summary":"Get company info","description":"Get company information associated with a domain / account.\n","operationId":"getDomainCompanyInfo","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/domain_id"}],"responses":{"200":{"$ref":"#/components/responses/CompanyInfoResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Create company info
> Create company information for a domain / account.\
> Company info is required for domain compliance verification.
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"domain_id":{"name":"domain_id","in":"path","required":true,"description":"Domain ID","schema":{"type":"integer"}}},"schemas":{"CompanyInfoRequest":{"type":"object","required":["name","address","city","country","zip_code","website_url"],"properties":{"name":{"type":"string","description":"Company or individual name"},"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City"},"country":{"type":"string","description":"Country"},"phone":{"type":"string","description":"Phone number"},"zip_code":{"type":"string","description":"ZIP or postal code"},"privacy_policy_url":{"type":"string","format":"uri","description":"URL to the privacy policy page"},"terms_of_service_url":{"type":"string","format":"uri","description":"URL to the terms of service page"},"website_url":{"type":"string","format":"uri","description":"Company website URL"},"info_level":{"type":"string","enum":["business","individual"],"description":"Whether the sender is a business or individual"}}},"CompanyInfo":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Company or individual name"},"address":{"type":["string","null"],"description":"Street address"},"city":{"type":["string","null"],"description":"City"},"country":{"type":["string","null"],"description":"Country"},"phone":{"type":["string","null"],"description":"Phone number"},"zip_code":{"type":["string","null"],"description":"ZIP or postal code"},"privacy_policy_url":{"type":["string","null"],"format":"uri","description":"URL to the privacy policy page"},"terms_of_service_url":{"type":["string","null"],"format":"uri","description":"URL to the terms of service page"},"website_url":{"type":["string","null"],"format":"uri","description":"Company website URL or LinkedIn / personal website"},"info_level":{"type":"string","enum":["business","individual"],"description":"Whether the sender is a business or individual"}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"type":"object","description":"Validation errors per field. Keys are attribute names; values are arrays of human-readable messages.\nSome endpoints may also return a `base` key with general validation errors.","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"CompanyInfoResponse":{"description":"Company information","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyInfo"}}}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"UnprocessableEntity":{"description":"Validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}}},"paths":{"/api/domains/{domain_id}/company_info":{"post":{"summary":"Create company info","description":"Create company information for a domain / account.\nCompany info is required for domain compliance verification.\n","operationId":"createDomainCompanyInfo","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/domain_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company_info"],"properties":{"company_info":{"$ref":"#/components/schemas/CompanyInfoRequest"}}}}}},"responses":{"200":{"$ref":"#/components/responses/CompanyInfoResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
## Update company info
> Update company information for a domain / account. All fields are optional;\
> only the fields provided in the request will be updated.
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"domains","description":"Configure and verify domains for email sending to ensure deliverability.\n"}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"domain_id":{"name":"domain_id","in":"path","required":true,"description":"Domain ID","schema":{"type":"integer"}}},"schemas":{"CompanyInfoUpdateRequest":{"type":"object","description":"All fields are optional. Only the fields provided in the request will be updated.\n","properties":{"name":{"type":"string","description":"Company or individual name"},"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City"},"country":{"type":"string","description":"Country"},"phone":{"type":"string","description":"Phone number"},"zip_code":{"type":"string","description":"ZIP or postal code"},"privacy_policy_url":{"type":"string","format":"uri","description":"URL to the privacy policy page"},"terms_of_service_url":{"type":"string","format":"uri","description":"URL to the terms of service page"},"website_url":{"type":"string","format":"uri","description":"Company website URL"},"info_level":{"type":"string","enum":["business","individual"],"description":"Whether the sender is a business or individual"}}},"CompanyInfo":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Company or individual name"},"address":{"type":["string","null"],"description":"Street address"},"city":{"type":["string","null"],"description":"City"},"country":{"type":["string","null"],"description":"Country"},"phone":{"type":["string","null"],"description":"Phone number"},"zip_code":{"type":["string","null"],"description":"ZIP or postal code"},"privacy_policy_url":{"type":["string","null"],"format":"uri","description":"URL to the privacy policy page"},"terms_of_service_url":{"type":["string","null"],"format":"uri","description":"URL to the terms of service page"},"website_url":{"type":["string","null"],"format":"uri","description":"Company website URL or LinkedIn / personal website"},"info_level":{"type":"string","enum":["business","individual"],"description":"Whether the sender is a business or individual"}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"type":"object","description":"Validation errors per field. Keys are attribute names; values are arrays of human-readable messages.\nSome endpoints may also return a `base` key with general validation errors.","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"CompanyInfoResponse":{"description":"Company information","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyInfo"}}}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"Forbidden":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"UnprocessableEntity":{"description":"Validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}}},"paths":{"/api/domains/{domain_id}/company_info":{"patch":{"summary":"Update company info","description":"Update company information for a domain / account. All fields are optional;\nonly the fields provided in the request will be updated.\n","operationId":"updateDomainCompanyInfo","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/domain_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company_info"],"properties":{"company_info":{"$ref":"#/components/schemas/CompanyInfoUpdateRequest"}}}}}},"responses":{"200":{"$ref":"#/components/responses/CompanyInfoResponse"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.mailtrap.io/developers/email-sending/domains.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.