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:[email protected]; ruf=mailto:[email protected]; 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": "[email protected]",
      "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

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:[email protected]; ruf=mailto:[email protected]; 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": "[email protected]",
  "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

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:[email protected]; ruf=mailto:[email protected]; 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": "[email protected]",
  "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

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

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:[email protected]; ruf=mailto:[email protected]; 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": "[email protected]",
  "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

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": "[email protected]"
  }'

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"
  }
}