가이드

작성자 Matt Connor 2026-10-11

VPS에 일회용 이메일 수신함 구축하기: Mailpit 설정 가이드

Q: 자가 호스팅하는 일회용 이메일 수신함이 오픈 릴레이인가요?

릴레이 기능을 끄면 그렇지 않습니다. 기본적으로 Mailpit은 외부로 메일을 발송하지 않습니다. MP_SMTP_RELAY_CONFIG 옵션은 사용자가 선택한 메시지를 수동으로 릴레이할 때만 사용하며, 자동 릴레이를 위해서는 MP_SMTP_RELAY_ALL 또는 MP_SMTP_RELAY_MATCHING 설정이 추가로 필요합니다. 이 설정을 비워두면 포트 1025에 접근한 외부인이 서버를 통해 메일을 보낼 수 없습니다. 다만 저장 공간을 채울 수는 있으므로, SMTP 포트는 애플리케이션만 접근할 수 있는 주소에 바인딩하십시오. Compose에서 1025:1025로 설정하면 모든 호스트 주소에 바인딩되며, Docker의 NAT 규칙이 우선 적용되므로 sudo ufw deny 1025/tcp 설정을 추가해도 포트는 닫히지 않습니다.

Q: 수신함이 디스크를 가득 채우지 않게 하려면 어떻게 해야 하나요?

MP_MAX_MESSAGES를 적절한 숫자로 유지하고 MP_MAX_AGE 설정을 추가하십시오. 기본 제한은 500개이며, 0로 설정하면 개수 기반 삭제가 비활성화됩니다. 따라서 MP_MAX_AGE를 설정하지 않으면 아무것도 삭제되지 않아 첨부 파일이 포함된 메일이 계속 쌓이게 됩니다. MP_MAX_AGE은 시간이나 일 단위(예: 36h 또는 14d)를 지원합니다. API는 웹 인터페이스와 동일한 자격 증명을 사용하므로, CI 종료 단계에서 curl -u qa:yourpassword -X DELETE http://127.0.0.1:8025/api/v1/messages을 호출하여 저장소를 비우십시오. Inbucket은 INBUCKET_STORAGE_RETENTIONPERIOD(72시간) 및 INBUCKET_STORAGE_MAILBOXMSGCAP(300개) 설정을 통해 동일한 기능을 수행합니다.

Mailpit을 사용하여 스테이징 환경의 모든 테스트 메일을 안전하게 차단하고 웹 UI로 확인하는 방법을 설명합니다. Docker Compose를 활용해 외부 발송을 방지하고 실제 고객에게 메일이 전달되는 사고를 원천 차단하는 구축 과정을 상세히 안내합니다.

일회용 이메일 수신함이란 무엇인가

일회용 이메일 수신함은 모든 주소로 오는 메일을 수신하되 실제로는 아무 곳으로도 전달하지 않는 소규모 SMTP(Simple Mail Transfer Protocol) 서버입니다. 스테이징 환경의 애플리케이션은 실제 메일 제공업체 대신 이 서버로 메일을 보내며, 모든 메시지는 이곳에 머무릅니다. 웹 인터페이스를 통해 도착한 메일을 확인할 수 있으므로, 수신자 목록이 잘못되었거나 템플릿이 깨져 있더라도 메일이 외부로 나가지 않아 아무런 문제가 발생하지 않습니다.

이 가이드에서는 Docker Compose를 사용하여 단일 VPS에 이를 구축합니다. Mailpit을 모든 메일을 받아내는 싱크(sink)로 사용합니다. Mailpit의 SMTP 리스너는 애플리케이션만 접근할 수 있는 곳에 바인딩하고, 웹 인터페이스는 TLS(Transport Layer Security)와 비밀번호가 적용된 nginx 뒤에 배치하며, 보관 제한을 설정하여 수신함이 디스크를 가득 채우지 않도록 합니다. Compose 사용이 처음이라면 VPS를 위한 Compose 기초에서 이 가이드가 가정하는 파일 구조를 확인할 수 있습니다.

이 결과물은 메일 서버가 아닌 테스트 도구입니다. 계정 기능, 메일 전달 기능, 스팸 필터링 기능은 없습니다. 실제 사용자를 위한 메일 수신함은 Mailcow와 같은 완전한 메일 서버가 필요하며, 이는 훨씬 더 큰 규모의 작업입니다.

Mailpit, Inbucket, MailHog 비교: 어떤 메일 싱크를 사용할 것인가

이 작업을 수행하는 도구는 세 가지가 있습니다. 이 도구들을 구분 짓는 요소는 유지보수 상태, 리스닝 포트, 그리고 메시지 수신 후 처리 능력입니다. 아래 버전은 2026년 10월 기준으로 확인되었습니다.

MailHog(mailhog/mailhog)는 SMTP를 위해 1025번 포트에서 대기하며, 8025번 포트에서 인터페이스를 제공합니다. 여전히 작동은 하지만, 기본 브랜치에 2022년 8월 이후 커밋이 없으며 이슈 트래커에는 200개가 넘는 미해결 이슈가 쌓여 있습니다. 따라서 테스트 경로에서 패치되지 않은 의존성을 사용하게 될 위험이 있습니다. 새로운 작업에 이 도구를 선택하지 마십시오.

Inbucket(inbucket/inbucket)은 SMTP를 위해 2500번, 웹 인터페이스를 위해 9000번, POP3(Post Office Protocol version 3)를 위해 1100번 포트에서 대기합니다. 2026년 10월 10일에 버전 3.2.0이 출시되었습니다. 메시지를 /storage 하위의 파일로 저장하며 자체적으로 정리합니다. 이때 이미지는 INBUCKET_STORAGE_RETENTIONPERIOD=72h 및 INBUCKET_STORAGE_MAILBOXMSGCAP=300 설정을 사용합니다. 테스트 환경에서 HTTP 호출 대신 POP3 클라이언트 라이브러리로 메일을 수집해야 할 때 이 도구를 선택하십시오.

Mailpit(axllent/mailpit)은 MailHog와 동일한 1025번 및 8025번 포트를 사용하므로, 애플리케이션 설정을 변경하지 않고도 MailHog를 대체할 수 있습니다. 2026년 10월 11일에 버전 1.31.5가 출시되었으며, 1.30 라인은 8월의 1.30.7 버전을 끝으로 종료되었습니다. 이 도구는 본 가이드에서 필요한 기능을 바이너리 내부에 포함하고 있습니다. 웹 인터페이스 및 API(Application Programming Interface)를 위한 비밀번호 파일, 메시지 개수 제한, 보관 기간 제한, 수신자 필터 기능이 여기에 해당합니다. 이 가이드의 나머지 부분은 Mailpit을 기준으로 진행합니다.

캐치올(catch-all)의 작동 원리와 DNS가 관여하지 않는 이유

애플리케이션은 여기서 메시지를 어디로 전달할지 조회하지 않습니다. 호스트와 포트를 지정하면 애플리케이션은 TCP 연결을 열고 RCPT TO:<anyone@example.test>을 알립니다. Mailpit은 수신자가 누구든 관계없이 이를 수락하여 메시지를 저장하며, 아무것도 전달하지 않습니다. 도메인 이름은 해석되지 않으므로 .test이 도메인 이름 시스템(DNS)상에 존재하지 않는 예약된 이름임에도 example.test은 정상적으로 작동합니다.

이것이 전체 메커니즘이며, 기본적으로 받은 편지함이 안전한 이유입니다. MX(mail exchanger) 레코드는 관여하지 않으며, 실제 전달 시도도 이루어지지 않으므로 어떤 메시지도 실제 사용자에게 도달할 수 없습니다.

스테이징 애플리케이션을 싱크(sink)로 연결

애플리케이션이 동일한 Compose 프로젝트 내에서 컨테이너로 실행될 때는 애플리케이션의 SMTP 호스트를 mailpit로 설정하고, 호스트에서 직접 실행될 때는 127.0.0.1으로 설정합니다. 포트는 1025로 설정하고, TLS는 끄며, 사용자 이름과 비밀번호는 비워 둡니다. Mailpit은 익명 메일을 허용합니다.

일부 프레임워크는 자격 증명 없이는 메일 발송을 거부합니다. MP_SMTP_AUTH_ACCEPT_ANY=1을 사용하면 Mailpit이 모든 사용자 이름과 비밀번호를 수락하며, MP_SMTP_AUTH_ALLOW_INSECURE=1는 암호화되지 않은 연결에서 PLAIN 및 LOGIN 메커니즘을 허용합니다. 이 두 설정은 리스너가 인터넷에서 접근할 수 없는 환경에서만 안전하며, 아래의 배포 설정이 이를 강제합니다.

MP_SMTP_ALLOWED_RECIPIENTS은 도입 초기부터 설정하는 것이 좋습니다. 이 설정은 정규 표현식을 사용하여 일치하지 않는 모든 수신자를 거부합니다. 테스트 도메인을 지정해 두면, 실제 고객 주소가 포함된 스테이징 데이터베이스를 사용하더라도 메일이 싱크에 조용히 쌓이는 대신 애플리케이션 로그에 명확한 실패 기록이 남게 됩니다.

Docker Compose 파일

먼저 웹 인터페이스를 위한 디렉터리와 비밀번호 파일을 생성합니다. htpasswd -B는 bcrypt 해시를 기록하며, Mailpit은 일반 텍스트뿐만 아니라 bcrypt도 읽을 수 있습니다.

mkdir -p ~/mailpit/data
cd ~/mailpit
sudo apt update && sudo apt install -y apache2-utils
htpasswd -B -c data/ui-auth qa

compose.yaml를 작성합니다:

services:
  mailpit:
    image: axllent/mailpit:v1.31
    container_name: mailpit
    restart: unless-stopped
    ports:
      - "127.0.0.1:8025:8025"
      - "127.0.0.1:1025:1025"
    volumes:
      - ./data:/data
    environment:
      MP_DATABASE: /data/mailpit.db
      MP_MAX_MESSAGES: 2000
      MP_MAX_AGE: 14d
      MP_UI_AUTH_FILE: /data/ui-auth
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1
      MP_SMTP_ALLOWED_RECIPIENTS: '@example\.test$$'

달러 기호를 두 번 쓴 것은 오타가 아닙니다. Compose는 단일 $을 변수 확장의 시작으로 읽기 때문에, $$을 사용해야 리터럴 달러 기호 하나를 컨테이너로 전달할 수 있습니다. 정규식은 @example\.test$로 Mailpit에 전달됩니다.

서비스를 시작하고 상태를 확인합니다:

docker compose up -d
docker compose ps

STATUS 열은 Up ... (healthy)으로 표시되어야 합니다. 이미지 자체에 15초마다 /mailpit readyz을 실행하는 헬스체크가 포함되어 있으므로, 컨테이너가 starting 상태로 유지되거나 unhealthy으로 바뀐다면 보통 컨테이너 내부의 8025 포트에서 서비스가 응답하지 않는 것입니다. 이 검사는 MP_ 환경 변수에서 설정을 가져오지만 명령줄 플래그는 참조하지 않으며, 이것이 본 가이드에서 모든 설정을 environment: 아래에 작성하는 이유 중 하나입니다. 대신 옵션을 플래그로 전달하면 Mailpit은 정상적으로 작동함에도 검사 결과는 unhealthy으로 보고될 수 있습니다. 다른 설정을 변경하기 전에 docker compose logs mailpit을 읽어보시기 바랍니다.

공개된 두 포트 모두 주소를 포함하며, 해당 주소가 보안 제어 역할을 합니다. 컨테이너 내부에서 Mailpit은 0.0.0.0에서 수신 대기하는데, 컨테이너는 고유한 네트워크 네임스페이스를 가지므로 이는 문제가 없습니다. 매핑의 왼쪽 부분은 외부에서 누가 접근할 수 있는지를 결정합니다. 8025:8025를 작성하면 Docker는 공용 주소를 포함하여 호스트의 모든 주소에 바인딩합니다.

스테이징 앱이 동일한 파일 내의 서비스라면 1025 매핑을 완전히 삭제하고 앱이 1025 포트의 mailpit 호스트 이름을 가리키도록 설정하십시오. 공유 Compose 네트워크에 있는 컨테이너들은 서로 직접 통신할 수 있으므로, SMTP 포트는 호스트에 전혀 노출되지 않습니다. Compose 네트워크가 서비스 이름을 확인하는 방법에서 해당 조회 방식을 다룹니다.

메시지 하나를 전송하고 수신 여부 확인

python3 - <<'EOF'
import smtplib
from email.message import EmailMessage

m = EmailMessage()
m["From"] = "staging@example.test"
m["To"] = "anyone@example.test"
m["Subject"] = "Mailpit smoke test"
m.set_content("If this appears in the web interface, the sink works.")
with smtplib.SMTP("127.0.0.1", 1025) as s:
    s.send_message(m)
EOF

스크립트는 성공 시 아무것도 출력하지 않습니다. API를 통해 메시지가 저장되었는지 확인합니다:

curl -s -u qa:yourpassword http://127.0.0.1:8025/api/v1/messages

이 요청은 저장된 메시지 목록을 JSON 형식으로 반환합니다. -u 플래그를 제거하면 동일한 요청이 거부됩니다. MP_UI_AUTH_FILE이 API와 웹 인터페이스를 모두 보호하기 때문입니다. 받은 편지함을 읽는 모든 테스트는 해당 자격 증명을 함께 전송해야 합니다.

Python 스크립트에서 발생하는 ConnectionRefusedError은 127.0.0.1:1025에서 수신 대기 중인 서비스가 없음을 의미합니다. SMTP 매핑을 제거했다면 이는 예상된 결과이며, 이후 확인 작업은 동일한 Compose 네트워크 내의 컨테이너에서 실행해야 합니다.

nginx를 사용하여 웹 인터페이스를 암호로 보호하며 게시하기

현재 인터페이스는 루프백 주소에서만 응답합니다. nginx는 TLS를 종료하고 요청이 도달하기 전에 암호를 요구합니다.

sudo htpasswd -B -c /etc/nginx/mailpit.htpasswd qa

server {
    listen 443 ssl;
    server_name mail-test.example.com;

    ssl_certificate     /etc/letsencrypt/live/mail-test.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mail-test.example.com/privkey.pem;

    auth_basic           "mailpit";
    auth_basic_user_file /etc/nginx/mailpit.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8025;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo nginx -t && sudo systemctl reload nginx로 구문 검사를 수행한 후 설정을 다시 불러옵니다. 프록시 설정이 처음이라면 리버스 프록시 블록의 각 지시어가 하는 역할을 한 번 읽어보는 것이 좋습니다.

nginx 파일과 data/ui-auth에 동일한 사용자 이름과 암호를 사용하십시오. nginx는 브라우저의 Authorization 헤더를 업스트림으로 전달하므로, 자격 증명이 일치하면 단일 프롬프트로 두 검사를 모두 통과할 수 있습니다. 자격 증명이 다르면 브라우저가 한 세트를 유지하게 되어 두 번째 검사에서 거부됩니다.

Upgrade 및 Connection 헤더는 장식이 아닙니다. Mailpit은 WebSocket을 통해 열려 있는 페이지로 새 메일을 푸시하는데, 해당 헤더 없이 HTTP/1.1로 실행되는 프록시는 연결을 업그레이드할 수 없습니다. 이 경우 페이지는 올바르게 로드되지만 상태가 변하지 않습니다. 메일이 도착하고 API가 이를 표시하더라도 페이지를 새로고침하기 전까지 목록은 그대로 유지됩니다.

두 잠금 장치를 모두 유지하십시오. nginx 암호는 공용 주소를 보호하며, MP_UI_AUTH_FILE은 8025 포트 자체를 보호합니다. 이는 스테이징 앱이 생성한 모든 암호 재설정 링크가 보존 기간 동안 해당 인터페이스에서 읽힐 수 있으므로 매우 중요합니다.

싱크가 오픈 릴레이가 되지 않도록 하십시오

오픈 릴레이는 누구에게서나 메시지를 받아 임의의 목적지로 전달하는 SMTP 서버를 의미합니다. 스패머들은 항상 오픈 릴레이를 탐색하며, 귀하의 주소에서 이를 발견하면 남용 보고서가 접수되고 계정이 정지될 수 있습니다.

Mailpit은 기본적으로 아무것도 외부로 전송하지 않으므로 기본 상태에서는 오픈 릴레이가 아닙니다. Mailpit에는 두 가지 아웃바운드 기능이 있으며, 설정을 구성하기 전까지는 모두 비활성화되어 있습니다. MP_SMTP_RELAY_CONFIG은 릴레이 설정 파일을 지정하고 인터페이스에서 릴레이 동작을 활성화하는데, 이를 통해 선택한 메시지를 해당 서버로 보낼 수 있습니다. 자동 릴레이를 위해서는 MP_SMTP_RELAY_ALL(기본값 false) 또는 MP_SMTP_RELAY_MATCHING과 같은 추가 스위치가 필요합니다. MP_SMTP_FORWARD_CONFIG 또는 MP_SMTP_FORWARD_* 변수로 설정하는 전달(Forwarding) 기능은 들어오는 모든 메시지를 지정한 고정 주소로 복사합니다. 이 설정들을 모두 비워두는 것은 의도적인 선택입니다.

이러한 안전한 상태를 잃게 되는 경우는 두 가지입니다. 들어오는 모든 메시지를 원래 수신자에게 보내고 MP_SMTP_ALLOWED_RECIPIENTS를 무시하는 MP_SMTP_RELAY_ALL을 켜고 SMTP 포트를 인터넷에 노출하면, 즉시 오픈 릴레이가 구축됩니다. MP_SMTP_RELAY_MATCHING도 패턴이 일치하는 모든 수신자에 대해 동일한 동작을 수행합니다. 릴레이 설정 없이 포트만 노출하면 외부인이 메일을 보낼 수는 없지만, 저장 공간을 채우거나 팀이 신뢰하는 인터페이스에 콘텐츠를 삽입할 수 있습니다. 전달 기능이 켜져 있다면, 그들의 메시지는 복사본을 받는 모든 받은 편지함으로 전달됩니다.

Docker 호스트에서 발생하는 함정은 방화벽입니다. 포트를 게시하면 Docker가 nat 테이블에 자체 규칙을 작성하며, 컨테이너로 향하는 트래픽은 ufw(uncomplicated firewall) 규칙이 적용되기 전에 해당 테이블에서 처리됩니다. sudo ufw deny 1025/tcp은 성공을 보고하지만 아무것도 변경하지 않습니다. Docker가 ufw를 우회하여 포트를 게시하는 이유에서 체인 순서를 확인하십시오.

해결책은 방화벽 규칙이 아니라 매핑 주소를 설정하는 것입니다. 실제로 어떤 주소에 바인딩되어 있는지 확인하십시오:

sudo ss -ltnp | grep -E ':(1025|8025)'

정상적인 출력은 127.0.0.1:1025 및 127.0.0.1:8025을 보여줍니다. 0.0.0.0:1025라고 표시된 줄은 매핑 주소가 누락되어 싱크가 인터넷을 향해 열려 있음을 의미합니다. 다른 머신에서 nc -vz mail-test.example.com 1025을 실행했을 때 타임아웃이 발생하거나 거부되어야 합니다.

애플리케이션이 다른 서버에 있는 경우, 두 서버를 연결하기 위해 1025 포트를 개방하지 마십시오. 두 머신을 사설 네트워크나 VPN 터널에 배치하고, 매핑을 해당 인터페이스 주소에 바인딩하십시오.

실제 인바운드 메일을 수신하려는 경우에만 MX 레코드를 게시하십시오

MX(mail exchanger) 레코드는 도메인으로 들어오는 메일을 수신할 호스트를 다른 메일 서버에 알리는 역할을 합니다. MX 레코드를 생략한다고 해서 메일 수신이 자동으로 차단되지는 않습니다. RFC 5321 5.1절에 명시된 대로, 도메인에 MX 레코드가 없으면 발신 서버는 해당 도메인의 주소(A 또는 AAAA) 레코드를 참조하게 되며, 웹 인터페이스를 위해 이 서버를 가리키는 호스트네임에는 이미 주소 레코드가 설정되어 있기 때문입니다. 인터넷 메일이 서버로 들어오지 못하게 막는 것은 서버의 25번 포트에서 아무것도 수신 대기하지 않기 때문입니다. 받은 편지함에는 오직 본인의 애플리케이션이 제출한 메일만 저장되며, 이것이 테스트 메일함의 용도입니다.

실제 메일을 수신하려면 발신 서버가 이 서버를 찾을 수 있는 DNS 레코드(MX 레코드 또는 대체 주소 레코드)가 필요하며, Mailpit이 25번 포트(MP_SMTP_BIND_ADDR=0.0.0.0:25)에서 수신 대기 중이어야 하고, 해당 포트가 열려 있어야 합니다. 이 순간부터 귀하는 해당 도메인의 모든 주소에 대해 공개적인 캐치올(catch-all) 서버를 운영하게 됩니다. 다음 사항을 명확히 인지하십시오.

DNS 레코드가 게시되면 수일 내에 스팸이 시작됩니다. 수집기(harvester)가 DNS를 읽기 때문입니다. 이후 사전 공격(dictionary attack)을 통해 흔한 이름들을 대입하며 모든 시도에 대해 메시지를 저장합니다.
낯선 발신자가 보낸 첨부 파일이 디스크에 저장되어 남게 됩니다. 필터링이 없으므로 알 수 없는 발신자의 아카이브가 본인의 테스트 메일과 함께 쌓입니다.
도메인을 알게 된 누구나 해당 도메인의 주소로 타사 서비스에 가입할 수 있으며, 인증 메일이 서버로 전달됩니다. 비밀번호 보안이 허술해지면 해당 계정들은 받은 편지함을 읽는 사람의 소유가 됩니다.
메일 양을 직접 제어할 수 없게 되므로, 보관 기간 제한은 단순한 정리 작업을 넘어 서버 부하를 관리하는 필수 요소가 됩니다.

메일 발송 가능 여부를 확인하기 위해 실제 인바운드 메일이 필요하다면 전용 서브도메인을 할당하고, MP_MAX_AGE를 짧게 유지하며, 그 안의 모든 데이터를 공개 정보로 취급하십시오. 사람들이 실제로 의존해야 하는 메일함이 필요하다면 필터링과 백업 기능을 갖춘 실제 메일 서버를 운영해야 합니다.

보존 정책: 제한 없는 catch-all 설정이 디스크를 채우는 방식

Mailpit은 기본적으로 500개의 메시지를 보관하며, 이를 초과하는 가장 오래된 메시지부터 주기적으로 삭제합니다. MP_MAX_MESSAGES: 0 옵션을 사용하면 이 제한이 해제되며, MP_MAX_AGE 설정이 없는 경우 자동으로 삭제되는 항목이 없으므로 catch-all 설정이 디스크를 가득 채워도 아무도 알아차리지 못하게 됩니다. MP_MAX_AGE 옵션은 시간 제한을 추가하며, 메시지 개수 제한과 함께 사용하거나 단독으로 사용할 수 있습니다. 시간 단위는 시간(hours)이나 일(days)로 지정하며, 36h 또는 14d 형식으로 작성합니다.

MP_DATABASE 옵션은 데이터의 영속성을 결정합니다. 이 옵션이 없으면 Mailpit은 프로세스가 종료될 때 삭제되는 임시 파일에 메일을 기록하므로, 재시작할 때마다 받은 편지함이 비워집니다. 이 옵션을 사용하면 재시작 후에도 메일이 유지되며 파일 크기가 계속 증가합니다.

디스크 공간을 소모하는 주범은 첨부 파일입니다. 매일 밤 2 MB 크기의 PDF 보고서를 300개의 테스트 주소로 발송하는 작업은 매일 600 MB의 용량을 차지하며, 메시지 개수 제한만으로는 제때 대응할 수 없습니다. 해당 볼륨을 공유하는 다른 서비스의 용량을 고려하여 증가분을 예산에 반영하십시오. PhotoPrism 또는 Immich와 같이 미디어 사용량이 많은 서비스가 이미 소규모 VPS 디스크의 대부분을 점유하고 있을 가능성이 높기 때문입니다.

du -h ~/mailpit/data/mailpit.db
df -h /

제한 설정이 작동하기를 기다리기보다 CI 실행 사이에 저장소를 비우는 것이 좋습니다.

curl -s -u qa:yourpassword -X DELETE http://127.0.0.1:8025/api/v1/messages

Inbucket은 동일한 문제를 INBUCKET_STORAGE_RETENTIONPERIOD(이미지 기본값 72h) 및 INBUCKET_STORAGE_MAILBOXMSGCAP(300) 옵션으로 처리합니다. 어떤 소프트웨어를 사용하든 첫 번째 테스트 스위트를 연결하기 전에 제한 설정을 먼저 결정하십시오.

테스트 스위트에서 받은 편지함 읽기

GET /api/v1/messages는 저장된 항목을 나열하고, GET /api/v1/message/{ID}는 메시지 하나를 그 구성 요소 및 헤더와 함께 반환하며, GET /api/v1/search은 필터링을 수행하고, DELETE /api/v1/messages은 저장소를 비웁니다. 현재 실행 중인 버전에 대한 대화형 문서는 http://127.0.0.1:8025/api/v1/에서 제공됩니다.

유용한 테스트는 메시지를 전송하고, 메시지가 나타날 때까지 폴링(polling)한 뒤, 제목과 내부 링크를 확인하고 모든 항목을 삭제합니다. 단일 요청으로 처리하기보다는 짧은 재시도 루프를 사용하여 폴링하십시오. 백그라운드 워커에서 메일을 대기열에 넣는 애플리케이션은 Mailpit이 메시지를 수신하기 전에 전송 호출을 완료하기 때문입니다. 동일한 패턴이 자체 호스팅 API 테스트 및 모킹 도구에서도 나타나며, 이는 일반적으로 운영 환경에 영향을 주지 않는 스테이징 환경의 나머지 절반을 구성합니다.

FAQ

자가 호스팅하는 일회용 이메일 수신함이 오픈 릴레이인가요?

릴레이 기능을 끄면 그렇지 않습니다. 기본적으로 Mailpit은 외부로 메일을 발송하지 않습니다. MP_SMTP_RELAY_CONFIG 옵션은 사용자가 선택한 메시지를 수동으로 릴레이할 때만 사용하며, 자동 릴레이를 위해서는 MP_SMTP_RELAY_ALL 또는 MP_SMTP_RELAY_MATCHING 설정이 추가로 필요합니다. 이 설정을 비워두면 포트 1025에 접근한 외부인이 서버를 통해 메일을 보낼 수 없습니다. 다만 저장 공간을 채울 수는 있으므로, SMTP 포트는 애플리케이션만 접근할 수 있는 주소에 바인딩하십시오. Compose에서 1025:1025로 설정하면 모든 호스트 주소에 바인딩되며, Docker의 NAT 규칙이 우선 적용되므로 sudo ufw deny 1025/tcp 설정을 추가해도 포트는 닫히지 않습니다.

테스트 도메인에 MX 레코드가 필요한가요?

인터넷에서 메일을 직접 수신하려는 경우에만 필요하며, MX 레코드를 설정하지 않는 것만으로는 보안이 보장되지 않습니다. MX 레코드가 없으면 발송 서버는 해당 도메인의 A 또는 AAAA 레코드를 참조하므로, 인터넷 메일을 차단하는 유일한 방법은 포트 25를 열어두지 않는 것입니다. 이 경우 수신함에는 애플리케이션이 SMTP를 통해 제출한 메일만 저장됩니다. DNS를 서버로 지정하고 포트 25를 개방하면 누구나 메일을 보낼 수 있는 공개 수신함이 되며, 며칠 내로 스팸 메일, 무차별 대입 공격으로 인한 메시지 누적, 필터링되지 않은 외부 첨부 파일로 인해 디스크가 가득 차게 됩니다.

페이지를 새로고침해야만 메시지 목록이 업데이트되는 이유는 무엇인가요?

Mailpit은 WebSocket을 통해 열려 있는 페이지로 새 메일을 푸시합니다. nginx 설정의 location 블록에 proxy_http_version 1.1 설정과 Upgrade, Connection 헤더가 누락되면 연결을 업그레이드할 수 없어 페이지가 정상적으로 로드된 후 멈춰버립니다. 메일은 정상적으로 수신되고 API도 응답하지만, 페이지가 갱신되지 않아 수신함이 정지된 것처럼 보입니다. 해당 설정을 추가하고 nginx를 재시작한 뒤 페이지를 새로고침하십시오.

수신함이 디스크를 가득 채우지 않게 하려면 어떻게 해야 하나요?

MP_MAX_MESSAGES를 적절한 숫자로 유지하고 MP_MAX_AGE 설정을 추가하십시오. 기본 제한은 500개이며, 0로 설정하면 개수 기반 삭제가 비활성화됩니다. 따라서 MP_MAX_AGE를 설정하지 않으면 아무것도 삭제되지 않아 첨부 파일이 포함된 메일이 계속 쌓이게 됩니다. MP_MAX_AGE은 시간이나 일 단위(예: 36h 또는 14d)를 지원합니다. API는 웹 인터페이스와 동일한 자격 증명을 사용하므로, CI 종료 단계에서 curl -u qa:yourpassword -X DELETE http://127.0.0.1:8025/api/v1/messages을 호출하여 저장소를 비우십시오. Inbucket은 INBUCKET_STORAGE_RETENTIONPERIOD(72시간) 및 INBUCKET_STORAGE_MAILBOXMSGCAP(300개) 설정을 통해 동일한 기능을 수행합니다.

Mailpit, Inbucket, MailHog 중 무엇을 사용해야 하나요?

2026년 10월 기준, 신규 프로젝트에는 Mailpit을 권장합니다. MailHog도 여전히 작동하지만 기본 브랜치에 2022년 8월 이후 커밋이 없어 보안 취약점이 있는 의존성을 포함하고 있습니다. Inbucket은 활발히 유지보수되고 있으며(2026년 10월 기준 3.2.0 버전), 테스트 환경에서 POP3가 필요할 때 더 나은 선택입니다. Mailpit의 POP3 서버는 비밀번호 파일이나 MP_POP3_AUTH 변수를 통해 자격 증명을 제공해야만 시작됩니다. Mailpit은 MailHog와 동일한 포트(1025, 8025)를 사용하므로, Compose 파일에서 이미지 이름만 변경하면 쉽게 교체할 수 있습니다.

#email #testing#mailpit#inbucket#docker #self-hosting