Domains

Manage custom domains for receiving emails. Before you can receive emails on a domain, it must be verified via DNS TXT record and configured with MoMail’s MX records.

List Domains

Retrieve all domains associated with your account.

GET /domains

Response

{
  "success": true,
  "data": [
    {
      "domain_id": "dom_abc123",
      "domain_name": "example.com",
      "verified": true,
      "mx_configured": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
domain_id	string	Unique identifier for the domain
domain_name	string	The registered domain name
verified	boolean	Whether DNS verification is complete
mx_configured	boolean	Whether MX records are properly configured
created_at	string	ISO 8601 timestamp of domain creation

Create Domain

Register a new domain for email receiving.

POST /domains

Request Body

{
  "domain": "example.com"
}

Parameters

Field	Type	Required	Description
domain	string	Yes	Valid domain name (1-253 characters)

Response

{
  "success": true,
  "data": {
    "domain_id": "dom_abc123",
    "domain_name": "example.com",
    "verification_token": "momail-verify=xyz789abc...",
    "verified": false,
    "mx_configured": false,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

Note

Save the verification_token value. You will need to add this as a TXT record in your DNS.

Get Domain

Retrieve details for a specific domain.

GET /domains/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	Domain UUID

Response

{
  "success": true,
  "data": {
    "domain_id": "dom_abc123",
    "domain_name": "example.com",
    "verification_instructions": {
      "type": "TXT",
      "name": "_momail",
      "value": "momail-verify=xyz789abc..."
    },
    "verified": false,
    "mx_configured": false,
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

Verify Domain

Trigger DNS verification for a domain. MoMail checks for the TXT record and updates the domain status.

POST /domains/{id}/verify

Parameters

Parameter	Type	Required	Description
id	string	Yes	Domain UUID

Response (Success)

{
  "success": true,
  "data": {
    "verified": true,
    "mx_instructions": {
      "host": "mx.momail.io",
      "priority": 10
    }
  }
}

Response (Pending Verification)

{
  "success": false,
  "error": {
    "code": "VERIFICATION_FAILED",
    "message": "TXT record not found or does not match verification token",
    "details": {
      "expected_txt_record": "momail-verify=xyz789abc...",
      "instructions": "Add a TXT record to your DNS with the above value"
    }
  }
}

Delete Domain

Remove a domain from your account.

DELETE /domains/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	Domain UUID

Response

{
  "success": true,
  "data": {
    "message": "Domain deleted successfully"
  }
}

Caution

Deleting a domain will stop all email processing for that domain. Emails sent after deletion will bounce.

DNS Configuration

Verification TXT Record

Add this TXT record to verify domain ownership:

Type	Name	Value
TXT	_momail	momail-verify={your_token}

MX Record

After verification, add this MX record to receive emails:

Type	Host	Priority	Value
MX	@	10	mx.momail.io

Code Examples

cURL

# List domains
curl https://api.momail.io/v1/domains \
  -H "X-API-Key: your_key"

# Create domain
curl -X POST https://api.momail.io/v1/domains \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# Verify domain
curl -X POST https://api.momail.io/v1/domains/dom_abc123/verify \
  -H "X-API-Key: your_key"

# Delete domain
curl -X DELETE https://api.momail.io/v1/domains/dom_abc123 \
  -H "X-API-Key: your_key"

JavaScript

// List domains
const domains = await fetch('https://api.momail.io/v1/domains', {
  headers: { 'X-API-Key': 'your_key' }
}).then(r => r.json());

// Create domain
const newDomain = await fetch('https://api.momail.io/v1/domains', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ domain: 'example.com' })
}).then(r => r.json());

// Verify domain
const verification = await fetch(`https://api.momail.io/v1/domains/${domainId}/verify`, {
  method: 'POST',
  headers: { 'X-API-Key': 'your_key' }
}).then(r => r.json());

Python

import requests

headers = {'X-API-Key': 'your_key'}

# List domains
response = requests.get('https://api.momail.io/v1/domains', headers=headers)
domains = response.json()['data']

# Create domain
response = requests.post(
    'https://api.momail.io/v1/domains',
    headers=headers,
    json={'domain': 'example.com'}
)
domain_id = response.json()['data']['domain_id']

# Verify domain
response = requests.post(
    f'https://api.momail.io/v1/domains/{domain_id}/verify',
    headers=headers
)