Domains

Manage verified domains

Configure and verify domains for email sending to ensure deliverability.

List domains

get

Get all domains and their verification status

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Responses

200

List of domains

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

get/api/domains

cURLNode.jsPHPPythonRuby.NETJava

curl -X GET https://mailtrap.io/api/domains \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": 435,
      "domain_name": "mailtrap.io",
      "demo": false,
      "compliance_status": "compliant",
      "dns_verified": true,
      "dns_verified_at": "2024-12-26T09:40:44.161Z",
      "dns_records": [
        {
          "key": "verification",
          "domain": "ve6wza2rbpe60x7z.mailtrap.io",
          "type": "CNAME",
          "value": "smtp.mailtrap.live",
          "status": "pass",
          "name": "ve6wza2rbpe60x7z"
        },
        {
          "key": "spf",
          "domain": "mailtrap.io",
          "type": "TXT",
          "value": "v=spf1 include:_spf.smtp.mailtrap.live ~all",
          "status": "pass",
          "name": ""
        },
        {
          "key": "dkim1",
          "domain": "rwmt1._domainkey.mailtrap.io",
          "type": "CNAME",
          "value": "rwmt1.dkim.smtp.mailtrap.live",
          "status": "pass",
          "name": "rwmt1._domainkey"
        },
        {
          "key": "dkim2",
          "domain": "rwmt2._domainkey.mailtrap.io",
          "type": "CNAME",
          "value": "rwmt2.dkim.smtp.mailtrap.live",
          "status": "pass",
          "name": "rwmt2._domainkey"
        },
        {
          "key": "dmarc",
          "domain": "_dmarc.mailtrap.io",
          "type": "TXT",
          "value": "v=DMARC1; p=none; rua=mailto:[e-mail]; ruf=mailto:[e-mail]; rf=afrf; pct=100",
          "status": "pass",
          "name": "_dmarc"
        },
        {
          "key": "link_verification",
          "domain": "mt-link.mailtrap.io",
          "type": "CNAME",
          "value": "t.mailtrap.live",
          "status": "pass",
          "name": "mt-link"
        }
      ],
      "open_tracking_enabled": true,
      "click_tracking_enabled": true,
      "auto_unsubscribe_link_enabled": true,
      "custom_domain_tracking_enabled": true,
      "health_alerts_enabled": true,
      "critical_alerts_enabled": true,
      "alert_recipient_email": "[e-mail]",
      "permissions": {
        "can_read": true,
        "can_update": true,
        "can_destroy": true
      }
    }
  ]
}

Create domain

post

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

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Body

application/json

Responses

200

Domain details

application/json

idintegerOptional

domain_namestringOptional

demobooleanOptional

compliance_statusstring · enumOptional

Indicates the compliance verification status of the domain. The domain must reach compliant status before you can send emails in production.

• demo - A demo domain provided by Mailtrap. Can only send emails to the account owner.
• demo_exhausted - A demo domain that has used up its sending allowance. Cannot send emails.
• unverified_dns - Domain DNS records have not been verified yet. Open your domain on the Domains page and follow the Sending Domain Setup guide.
• missing_company_info - Account is missing required company information. Go to Company Information and fill in the required details.
• under_review - Domain is undergoing automatic compliance review. No action needed — typically completes within 2 minutes.
• awaiting_questionnaire - Automatic review required additional information. Open your domain on the Domains page and fill in the compliance questionnaire.
• awaiting_card_verification - Compliance questionnaire was submitted but credit card identity verification is still needed. Open your domain on the Domains page and enter card details. The charged amount is refunded immediately and the card is not stored.
• non_compliant - Domain did not pass compliance checks. Sending is not allowed. Contact Mailtrap Support for details and next steps.
• compliant - Domain has passed all compliance checks and is ready to send emails.
• suspended - Domain sending has been suspended. Contact Mailtrap Support to resolve the issue.

Possible values:

dns_verifiedbooleanOptional

dns_verified_atstring · nullableOptionalExample: 2024-12-26T09:40:44.161Z

open_tracking_enabledbooleanOptional

click_tracking_enabledbooleanOptional

auto_unsubscribe_link_enabledbooleanOptional

custom_domain_tracking_enabledbooleanOptional

health_alerts_enabledbooleanOptional

critical_alerts_enabledbooleanOptional

alert_recipient_emailstring · nullableOptional

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

422

Validation errors

application/json

post/api/domains

cURLNode.jsPHPPythonRuby.NETJava

curl -X POST https://mailtrap.io/api/domains \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": {
      "domain_name": "example.com"
    }
  }'

{
  "id": 435,
  "domain_name": "mailtrap.io",
  "demo": false,
  "compliance_status": "compliant",
  "dns_verified": true,
  "dns_verified_at": "2024-12-26T09:40:44.161Z",
  "dns_records": [
    {
      "key": "verification",
      "domain": "ve6wza2rbpe60x7z.mailtrap.io",
      "type": "CNAME",
      "value": "smtp.mailtrap.live",
      "status": "pass",
      "name": "ve6wza2rbpe60x7z"
    },
    {
      "key": "spf",
      "domain": "mailtrap.io",
      "type": "TXT",
      "value": "v=spf1 include:_spf.smtp.mailtrap.live ~all",
      "status": "pass",
      "name": ""
    },
    {
      "key": "dkim1",
      "domain": "rwmt1._domainkey.mailtrap.io",
      "type": "CNAME",
      "value": "rwmt1.dkim.smtp.mailtrap.live",
      "status": "pass",
      "name": "rwmt1._domainkey"
    },
    {
      "key": "dkim2",
      "domain": "rwmt2._domainkey.mailtrap.io",
      "type": "CNAME",
      "value": "rwmt2.dkim.smtp.mailtrap.live",
      "status": "pass",
      "name": "rwmt2._domainkey"
    },
    {
      "key": "dmarc",
      "domain": "_dmarc.mailtrap.io",
      "type": "TXT",
      "value": "v=DMARC1; p=none; rua=mailto:[e-mail]; ruf=mailto:[e-mail]; rf=afrf; pct=100",
      "status": "pass",
      "name": "_dmarc"
    },
    {
      "key": "link_verification",
      "domain": "mt-link.mailtrap.io",
      "type": "CNAME",
      "value": "t.mailtrap.live",
      "status": "pass",
      "name": "mt-link"
    }
  ],
  "open_tracking_enabled": true,
  "click_tracking_enabled": true,
  "auto_unsubscribe_link_enabled": true,
  "custom_domain_tracking_enabled": true,
  "health_alerts_enabled": true,
  "critical_alerts_enabled": true,
  "alert_recipient_email": "[e-mail]",
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true
  }
}

Get domain

get

Get details and verification status of a specific domain

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

domain_idintegerRequired

Domain ID

Example: 1

Responses

200

Domain details

application/json

idintegerOptional

domain_namestringOptional

demobooleanOptional

compliance_statusstring · enumOptional

Indicates the compliance verification status of the domain. The domain must reach compliant status before you can send emails in production.

• demo - A demo domain provided by Mailtrap. Can only send emails to the account owner.
• demo_exhausted - A demo domain that has used up its sending allowance. Cannot send emails.
• unverified_dns - Domain DNS records have not been verified yet. Open your domain on the Domains page and follow the Sending Domain Setup guide.
• missing_company_info - Account is missing required company information. Go to Company Information and fill in the required details.
• under_review - Domain is undergoing automatic compliance review. No action needed — typically completes within 2 minutes.
• awaiting_questionnaire - Automatic review required additional information. Open your domain on the Domains page and fill in the compliance questionnaire.
• awaiting_card_verification - Compliance questionnaire was submitted but credit card identity verification is still needed. Open your domain on the Domains page and enter card details. The charged amount is refunded immediately and the card is not stored.
• non_compliant - Domain did not pass compliance checks. Sending is not allowed. Contact Mailtrap Support for details and next steps.
• compliant - Domain has passed all compliance checks and is ready to send emails.
• suspended - Domain sending has been suspended. Contact Mailtrap Support to resolve the issue.

Possible values:

dns_verifiedbooleanOptional

dns_verified_atstring · nullableOptionalExample: 2024-12-26T09:40:44.161Z

open_tracking_enabledbooleanOptional

click_tracking_enabledbooleanOptional

auto_unsubscribe_link_enabledbooleanOptional

custom_domain_tracking_enabledbooleanOptional

health_alerts_enabledbooleanOptional

critical_alerts_enabledbooleanOptional

alert_recipient_emailstring · nullableOptional

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

get/api/domains/{domain_id}

cURLNode.jsPHPPythonRuby.NETJava

curl -X GET https://mailtrap.io/api/domains/{domain_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 435,
  "domain_name": "mailtrap.io",
  "demo": false,
  "compliance_status": "compliant",
  "dns_verified": true,
  "dns_verified_at": "2024-12-26T09:40:44.161Z",
  "dns_records": [
    {
      "key": "verification",
      "domain": "ve6wza2rbpe60x7z.mailtrap.io",
      "type": "CNAME",
      "value": "smtp.mailtrap.live",
      "status": "pass",
      "name": "ve6wza2rbpe60x7z"
    },
    {
      "key": "spf",
      "domain": "mailtrap.io",
      "type": "TXT",
      "value": "v=spf1 include:_spf.smtp.mailtrap.live ~all",
      "status": "pass",
      "name": ""
    },
    {
      "key": "dkim1",
      "domain": "rwmt1._domainkey.mailtrap.io",
      "type": "CNAME",
      "value": "rwmt1.dkim.smtp.mailtrap.live",
      "status": "pass",
      "name": "rwmt1._domainkey"
    },
    {
      "key": "dkim2",
      "domain": "rwmt2._domainkey.mailtrap.io",
      "type": "CNAME",
      "value": "rwmt2.dkim.smtp.mailtrap.live",
      "status": "pass",
      "name": "rwmt2._domainkey"
    },
    {
      "key": "dmarc",
      "domain": "_dmarc.mailtrap.io",
      "type": "TXT",
      "value": "v=DMARC1; p=none; rua=mailto:[e-mail]; ruf=mailto:[e-mail]; rf=afrf; pct=100",
      "status": "pass",
      "name": "_dmarc"
    },
    {
      "key": "link_verification",
      "domain": "mt-link.mailtrap.io",
      "type": "CNAME",
      "value": "t.mailtrap.live",
      "status": "pass",
      "name": "mt-link"
    }
  ],
  "open_tracking_enabled": true,
  "click_tracking_enabled": true,
  "auto_unsubscribe_link_enabled": true,
  "custom_domain_tracking_enabled": true,
  "health_alerts_enabled": true,
  "critical_alerts_enabled": true,
  "alert_recipient_email": "[e-mail]",
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true
  }
}

Delete domain

delete

Remove a domain from your account

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

domain_idintegerRequired

Domain ID

Example: 1

Responses

204

Domain successfully deleted

No content

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

delete/api/domains/{domain_id}

cURLNode.jsPHPPythonRuby.NETJava

curl -X DELETE https://mailtrap.io/api/domains/{domain_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

No content

Update domain

patch

Update configuration settings for a domain.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

domain_idintegerRequired

Domain ID

Example: 1

Body

application/json

Responses

200

Domain details

application/json

idintegerOptional

domain_namestringOptional

demobooleanOptional

compliance_statusstring · enumOptional

Indicates the compliance verification status of the domain. The domain must reach compliant status before you can send emails in production.

• demo - A demo domain provided by Mailtrap. Can only send emails to the account owner.
• demo_exhausted - A demo domain that has used up its sending allowance. Cannot send emails.
• unverified_dns - Domain DNS records have not been verified yet. Open your domain on the Domains page and follow the Sending Domain Setup guide.
• missing_company_info - Account is missing required company information. Go to Company Information and fill in the required details.
• under_review - Domain is undergoing automatic compliance review. No action needed — typically completes within 2 minutes.
• awaiting_questionnaire - Automatic review required additional information. Open your domain on the Domains page and fill in the compliance questionnaire.
• awaiting_card_verification - Compliance questionnaire was submitted but credit card identity verification is still needed. Open your domain on the Domains page and enter card details. The charged amount is refunded immediately and the card is not stored.
• non_compliant - Domain did not pass compliance checks. Sending is not allowed. Contact Mailtrap Support for details and next steps.
• compliant - Domain has passed all compliance checks and is ready to send emails.
• suspended - Domain sending has been suspended. Contact Mailtrap Support to resolve the issue.

Possible values:

dns_verifiedbooleanOptional

dns_verified_atstring · nullableOptionalExample: 2024-12-26T09:40:44.161Z

open_tracking_enabledbooleanOptional

click_tracking_enabledbooleanOptional

auto_unsubscribe_link_enabledbooleanOptional

custom_domain_tracking_enabledbooleanOptional

health_alerts_enabledbooleanOptional

critical_alerts_enabledbooleanOptional

alert_recipient_emailstring · nullableOptional

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

422

Validation errors

application/json

patch/api/domains/{domain_id}

cURL

curl -X PATCH https://mailtrap.io/api/domains/{domain_id} \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": {
      "open_tracking_enabled": true,
      "click_tracking_enabled": true,
      "auto_unsubscribe_link_enabled": false
    }
  }'

{
  "id": 435,
  "domain_name": "mailtrap.io",
  "demo": false,
  "compliance_status": "compliant",
  "dns_verified": true,
  "dns_verified_at": "2024-12-26T09:40:44.161Z",
  "dns_records": [
    {
      "key": "verification",
      "domain": "ve6wza2rbpe60x7z.mailtrap.io",
      "type": "CNAME",
      "value": "smtp.mailtrap.live",
      "status": "pass",
      "name": "ve6wza2rbpe60x7z"
    },
    {
      "key": "spf",
      "domain": "mailtrap.io",
      "type": "TXT",
      "value": "v=spf1 include:_spf.smtp.mailtrap.live ~all",
      "status": "pass",
      "name": ""
    },
    {
      "key": "dkim1",
      "domain": "rwmt1._domainkey.mailtrap.io",
      "type": "CNAME",
      "value": "rwmt1.dkim.smtp.mailtrap.live",
      "status": "pass",
      "name": "rwmt1._domainkey"
    },
    {
      "key": "dkim2",
      "domain": "rwmt2._domainkey.mailtrap.io",
      "type": "CNAME",
      "value": "rwmt2.dkim.smtp.mailtrap.live",
      "status": "pass",
      "name": "rwmt2._domainkey"
    },
    {
      "key": "dmarc",
      "domain": "_dmarc.mailtrap.io",
      "type": "TXT",
      "value": "v=DMARC1; p=none; rua=mailto:[e-mail]; ruf=mailto:[e-mail]; rf=afrf; pct=100",
      "status": "pass",
      "name": "_dmarc"
    },
    {
      "key": "link_verification",
      "domain": "mt-link.mailtrap.io",
      "type": "CNAME",
      "value": "t.mailtrap.live",
      "status": "pass",
      "name": "mt-link"
    }
  ],
  "open_tracking_enabled": true,
  "click_tracking_enabled": true,
  "auto_unsubscribe_link_enabled": true,
  "custom_domain_tracking_enabled": true,
  "health_alerts_enabled": true,
  "critical_alerts_enabled": true,
  "alert_recipient_email": "[e-mail]",
  "permissions": {
    "can_read": true,
    "can_update": true,
    "can_destroy": true
  }
}

Send setup instructions

post

Email DNS configuration instructions for the domain

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

domain_idintegerRequired

Domain ID

Example: 1

Body

application/json

emailstring · emailRequired

Email address to receive setup instructions

Responses

204

Instructions sent successfully

No content

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

422

Validation errors

application/json

post/api/domains/{domain_id}/send_setup_instructions

cURLNode.jsPHPPythonRuby.NETJava

curl -X POST https://mailtrap.io/api/domains/{domain_id}/send_setup_instructions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[e-mail]"
  }'

No content

Get company info

get

Get company information associated with a domain / account.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

domain_idintegerRequired

Domain ID

Example: 1

Responses

200

Company information

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

get/api/domains/{domain_id}/company_info

cURL

curl -X GET https://mailtrap.io/api/domains/{domain_id}/company_info \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": {
    "name": "Mailtrap",
    "address": "123 Main St",
    "city": "San Francisco",
    "country": "US",
    "phone": "[phone]",
    "zip_code": "94105",
    "privacy_policy_url": "https://mailtrap.io/privacy",
    "terms_of_service_url": "https://mailtrap.io/terms",
    "website_url": "https://mailtrap.io",
    "info_level": "business"
  }
}

Create company info

post

Create company information for a domain / account. Company info is required for domain compliance verification.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

domain_idintegerRequired

Domain ID

Example: 1

Body

application/json

Responses

200

Company information

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

422

Validation errors

application/json

post/api/domains/{domain_id}/company_info

cURL

curl -X POST https://mailtrap.io/api/domains/{domain_id}/company_info \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_info": {
      "name": "Mailtrap",
      "address": "123 Main St",
      "city": "San Francisco",
      "country": "US",
      "zip_code": "94105",
      "phone": "[phone]",
      "website_url": "https://mailtrap.io",
      "privacy_policy_url": "https://mailtrap.io/privacy",
      "terms_of_service_url": "https://mailtrap.io/terms",
      "info_level": "business"
    }
  }'

{
  "data": {
    "name": "Mailtrap",
    "address": "123 Main St",
    "city": "San Francisco",
    "country": "US",
    "phone": "[phone]",
    "zip_code": "94105",
    "privacy_policy_url": "https://mailtrap.io/privacy",
    "terms_of_service_url": "https://mailtrap.io/terms",
    "website_url": "https://mailtrap.io",
    "info_level": "business"
  }
}

Update company info

patch

Update company information for a domain / account. All fields are optional; only the fields provided in the request will be updated.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

API token in Api-Token header

Path parameters

domain_idintegerRequired

Domain ID

Example: 1

Body

application/json

Responses

200

Company information

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

422

Validation errors

application/json

patch/api/domains/{domain_id}/company_info

cURL

curl -X PATCH https://mailtrap.io/api/domains/{domain_id}/company_info \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_info": {
      "city": "New York",
      "zip_code": "10001"
    }
  }'

{
  "data": {
    "name": "Mailtrap",
    "address": "123 Main St",
    "city": "San Francisco",
    "country": "US",
    "phone": "[phone]",
    "zip_code": "94105",
    "privacy_policy_url": "https://mailtrap.io/privacy",
    "terms_of_service_url": "https://mailtrap.io/terms",
    "website_url": "https://mailtrap.io",
    "info_level": "business"
  }
}