API와 MCP를 통한 도메인 별칭

도메인 별칭을 사용하면 한 도메인이 다른 도메인의 수신 주소를 따르도록 할 수 있습니다. hello@company.example이 메일을 받을 수 있다면 두 번째 메일함이나 별칭을 만들고 관리하지 않아도 hello@brand.example로 온 메일을 같은 위치로 배달할 수 있습니다.

이 기능은 수신 전용입니다. From 주소를 만들거나 SMTP를 변경하지 않으며 누구도 연결된 도메인으로 메일을 보내게 하지 않습니다.

유용한 경우

기업에 여러 브랜드 도메인, 고객 메일을 계속 받는 이전 도메인, 또는 같은 받은편지함 이름을 공유해야 하는 국가별 도메인이 있을 때 도메인 별칭이 유용합니다.

예시:

hello@brand.example   → hello@company.example
billing@brand.example → billing@company.example

@ 앞부분은 정확히 동일하게 유지됩니다. 기본 도메인에 일치하는 주소가 없으면 TrekMail은 이를 임의로 만들지 않습니다.

요금제와 한도

연결된 도메인 하나는 한 번에 하나의 기본 도메인을 따를 수 있습니다. 기본 도메인 하나는 계정의 일반 도메인 한도 내에서 여러 연결된 도메인을 지원할 수 있습니다. 하나의 도메인은 연결된 도메인이면서 동시에 기본 도메인일 수 없으므로 라우팅이 단순하게 유지되고 루프가 방지됩니다.

두 도메인은 같은 계정에 속하고 수신 메일에 TrekMail을 사용하며 활성 상태이고 정상적인 MX 레코드를 보유해야 합니다. 이후 요금제, 계정 또는 DNS 상태가 변경되면 TrekMail은 저장된 연결을 유지하지만 요건이 복구될 때까지 배달을 일시 중지합니다.

우선순위가 유지되는 항목

도메인 별칭은 TrekMail이 연결된 도메인에 이미 구성된 정확한 주소를 확인한 후에만 실행됩니다. 기존 메일함, 별칭, 전달 주소, 메일함 전달 및 catch-all 설정은 문서에 명시된 우선순위를 유지합니다.

즉, 의도적으로 만든 sales@brand.example 규칙이 sales@company.example로 조용히 대체되지 않습니다.

REST API

세 엔드포인트는 연결된 도메인의 ID를 사용합니다.

기존 연동이 중단되지 않도록 엔드포인트는 원래의 /matching-addresses 경로를 유지합니다. 대시보드와 문서에서는 더 명확한 업계 용어인 도메인 별칭을 사용합니다.

PUT과 DELETE에는 Idempotency-Key 헤더가 필요합니다. 같은 키로 성공한 동일 요청을 반복해도 안전합니다.

도메인 연결

PUT /api/v1/domains/42/matching-addresses
Authorization: Bearer tm_live_...
Idempotency-Key: matching-brand-company-v1
Content-Type: application/json

{
  "primary_domain_id": 7
}

결과 확인

{
  "configured": true,
  "enabled": true,
  "delivering": true,
  "status": "delivering",
  "paused_reason": null,
  "alias_domain": {
    "id": 42,
    "domain": "brand.example"
  },
  "primary_domain": {
    "id": 7,
    "domain": "company.example"
  },
  "primary_domain_restricted": false
}

configured는 연결이 저장되었는지를 알려 줍니다. delivering은 현재 작동 중인지를 알려 줍니다. 저장된 행을 메일이 흐르고 있다는 증거로 간주하지 말고 두 값을 모두 확인하세요.

토큰이 연결된 도메인에는 접근할 수 있지만 기본 도메인에는 접근할 수 없는 경우 응답은 primary_domain_restricted를 true로 설정하고 기본 도메인의 식별 정보를 숨깁니다. 토큰의 허용 목록 밖에 있는 도메인을 절대 노출하지 않습니다.

배달 상태

MCP 도구

동일한 워크플로를 세 가지 도메인 도구에서 사용할 수 있습니다.

• get_domain_alias: 저장된 연결과 현재 배달 상태를 확인합니다.
• set_domain_alias: 기본 도메인을 연결하거나 변경합니다.
• remove_domain_alias: confirm_remove: true를 지정한 후 연결을 해제합니다.

호스팅 MCP는 OAuth 중에 승인된 권한을 적용합니다. 로컬 호스팅 MCP 관리자는 쓰기 작업에 명시적인 승인을 요구할 수 있습니다. 두 방식 모두 계정 요금제, 토큰 범위, 도메인 허용 목록 및 서버 측 유효성 검사를 적용합니다.

도구 이름과 고객 대상 제목에는 도메인 별칭을 사용합니다. REST 엔드포인트는 호환성을 위해 원래 경로를 유지합니다.

안전한 제거와 다운그레이드

연결을 제거해도 어느 도메인이나 메일함도 삭제되지 않습니다. 정확한 메일함, 별칭, 전달 주소 및 catch-all 규칙은 변경되지 않습니다. 일치 기능에만 의존하던 일치하지 않는 주소는 반송되기 시작할 수 있으므로 제거를 확인하기 전에 도메인을 검토하세요.

연결된 도메인을 삭제하면 해당 연결이 자동으로 제거됩니다. 연결된 도메인이 계속 의존하는 동안에는 TrekMail이 기본 도메인을 삭제하지 않습니다. 먼저 해당 도메인의 연결을 해제하세요.

Nano로 다운그레이드하면 연결은 저장된 상태로 유지되지만 배달은 중지됩니다. Starter 이상으로 돌아가면 기본 도메인을 다시 입력하지 않아도 연결이 복구됩니다.

감사 추적

모든 API 또는 MCP 변경 사항은 AI 에이전트 및 API → 감사 로그에 표시됩니다. 연결 및 변경 이벤트에는 두 도메인 ID, 해당하는 경우 이전 기본 도메인, 작업을 수행한 토큰, 요청 ID와 시간이 기록됩니다. 제거 이벤트에는 제거된 연결이 기록됩니다. 이메일 내용이나 자격 증명은 이러한 이벤트에 기록되지 않습니다.

문제 해결 체크리스트

1. 두 도메인이 모두 활성으로 표시되고 수신 메일에 TrekMail을 사용하는지 확인합니다.
2. 두 도메인의 MX 레코드가 정상인지 확인합니다.
3. 계정이 Starter, Pro 또는 Agency를 사용 중인지 확인합니다.
4. configured, delivering, status, paused_reason을 함께 확인합니다.
5. 정확한 메일함, 별칭, 전달 주소 또는 catch-all 규칙이 이미 해당 주소를 담당하는지 확인합니다.
6. 최근 연결, 변경 또는 제거 작업은 감사 로그에서 검토합니다.