Custom Domains

Manage your custom domains for temporary addresses

List Domains

Retrieves the list of your custom domains.

GET /api/v1/domains

Required scope: domains:read

Example

curl -X GET https://api.junkmail.dev/api/v1/domains \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "domain": "my-startup.com",
      "status": "verified",
      "createdAt": "2024-01-10T08:00:00Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "domain": "test-domain.io",
      "status": "pending",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

---

Add a Domain

Adds a new custom domain. You will need to configure DNS records to verify it.

POST /api/v1/domains

Required scope: domains:manage

Request Body

Field	Type	Required	Description
domain	string	Yes	Domain name (max 255 characters, e.g.: my-startup.com)

The domain must match the format: letters, numbers, and hyphens, followed by an extension of at least 2 characters.

Example

curl -X POST https://api.junkmail.dev/api/v1/domains \
  -H "Authorization: Bearer jm_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "my-startup.com"
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "my-startup.com",
    "status": "pending",
    "dnsRecords": {
      "mx": {
        "type": "MX",
        "host": "my-startup.com",
        "value": "mx.junkmail.dev",
        "priority": 10
      },
      "txt": {
        "type": "TXT",
        "host": "my-startup.com",
        "value": "junkmail-verify=xxxxxxxxxxxx"
      }
    },
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

After adding the domain, configure the DNS records indicated in the response. Verification can take up to 48 hours.

---

Delete a Domain

Deletes a custom domain. Addresses using this domain will no longer receive emails.

DELETE /api/v1/domains/:id

Required scope: domains:manage

Example

curl -X DELETE https://api.junkmail.dev/api/v1/domains/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer jm_live_xxxx"

Response

{
  "message": "Domain deleted successfully"
}