1. 메일 보내기 개요

DXCMS 관리자 패널의 [메일 보내기] 메뉴는 회원 또는 지정된 이메일 주소로 HTML 메일을 발송하고, 서버 메일 환경(드라이버)과 SMTP 설정을 관리하는 도구입니다. 서버 환경을 자동으로 감지하여 최적의 메일 발송 방법을 선택하며, SMTP는 선택 사항입니다.

📌  접근 경로: 관리자 대시보드 → 메일 보내기 (또는 URL: /admin/sendmail)

1.1 화면 구성 — 3탭 구조

메일 보내기 화면은 3개의 탭으로 구성됩니다. 상단의 드라이버 상태 배지로 현재 메일 발송 가능 여부를 즉시 확인할 수 있습니다.
 

탭	기능 및 설명
✉ 메일 보내기	수신자를 선택하고 제목·내용을 입력하여 메일을 발송합니다. 발송 드라이버가 없으면 발송 버튼이 비활성화됩니다.
⚙ SMTP 설정	외부 SMTP 서버(Gmail·네이버·AWS SES 등) 정보를 설정합니다. SMTP 설정 완료 시 탭 옆 ● 초록 표시. 테스트 발송 기능 포함.
🖥 환경 정보	서버의 메일 드라이버 자동 감지 결과(SMTP/mail()/sendmail), 서버 환경 정보, 개발자용 커스텀 드라이버 등록 가이드 표시.

1.2 드라이버 자동 선택 우선순위

DxMailer 클래스는 서버 환경을 자동으로 감지하여 SMTP → mail() → sendmail 순서로 최적 드라이버를 선택합니다. 선택된 드라이버는 페이지 우측 상단의 배지로 표시됩니다.
 

우선순위	드라이버	조건	특징
1순위	SMTP	smtp_host 설정 + fsockopen() 가능	외부 SMTP 서버 연결. 가장 신뢰성 높음. Gmail·AWS SES 등 지원.
2순위	mail() 함수	PHP mail() 함수 활성화	서버 sendmail/Postfix 통해 발송. Linux 환경에서 별도 설정 불필요.
3순위	sendmail	popen() + sendmail 바이너리	sendmail 바이너리 직접 실행. mail()과 유사한 서버 사이드 발송.
없음	드라이버 없음	위 조건 모두 미충족	메일 발송 불가. SMTP 설정을 반드시 구성해야 합니다.

💡  Linux/Unix 서버(대부분의 웹호스팅•VPS)에서는 mail() 함수가 기본으로 활성화되어 있어 별도 SMTP 설정 없이 즉시 발송 가능합니다. SMTP는 발신 주소 인증, 스팸 방지, 전송률 개선이 필요할 때 설정하세요.

2. 메일 보내기 탭

[메일 보내기] 탭에서 수신자를 선택하고 메일 제목과 내용을 입력하여 발송합니다. 드라이버가 없는 경우 발송 버튼이 비활성화(opacity 40%)되며 경고 배너가 표시됩니다.

2.1 수신자 선택 — 3가지 방식

라디오 버튼으로 수신자 방식을 선택합니다. 선택에 따라 하단 입력 영역이 동적으로 변경됩니다.

방식 1: 직접 입력 (custom)

이메일 주소를 직접 입력합니다. 기본 선택값입니다.
 

입력 형식	이메일 주소를 콤마(,) 또는 줄바꿈(엔터)으로 구분하여 여러 개 입력 가능.
예시	a@example.com, b@example.com c@example.com
유효성 검증	각 이메일을 PHP filter_var(FILTER_VALIDATE_EMAIL)로 검증. 형식이 잘못된 이메일은 자동으로 제외됩니다.
활용 용도	특정 외부 이메일, 테스트 발송, 소수의 개별 수신자에게 발송할 때 사용.

방식 2: 전체 회원 (all)

활성(status=1) 상태이고 이메일이 등록된 모든 회원에게 발송합니다.
 

수신자 수	탭 레이블 옆에 현재 발송 가능 회원 수(N명)가 실시간으로 표시됩니다.
발송 조건	members 테이블 WHERE status=1 AND email!=''. 비활성 회원 및 이메일 미등록 회원 제외.
확인 창	발송 버튼 클릭 시 "전체 회원(N명)에게 발송합니다. 계속하시겠습니까?" 확인 창이 표시됩니다.
속도 제어	수신자가 10명 초과 시 건당 10ms(usleep(10000)) 간격으로 발송하여 서버 과부하를 방지합니다.

⚠️  전체 회원 발송은 대량 발송입니다. 스팸 방지 정책에 위반되지 않도록 발송 전 내용을 반드시 검토하고, 수신자가 원하지 않는 광고성 메일은 발송하지 마세요.

방식 3: 권한별 발송 (role)

특정 권한(role)의 회원에게만 선택적으로 발송합니다.
 

권한값	대상	설명
member	일반 회원 (N명)	role=member인 활성 회원에게만 발송.
manager	매니저 (N명)	role=manager인 활성 회원에게만 발송.
admin	관리자 (N명)	role=admin인 활성 회원에게만 발송.

💡  권한별 발송은 운영진 공지, 관리자 알림 등 특정 그룹에만 전달해야 하는 메일에 유용합니다.

2.2 메일 내용 입력

필드	필수 여부	설명
제목 (mail_subject)	필수	수신자에게 표시되는 메일 제목. 간결하고 명확하게 작성하세요. 클라이언트 측(JavaScript)에서도 빈 값 체크합니다.
내용 (mail_body)	필수	HTML 태그 사용 가능. 에디터 없이 텍스트 영역(textarea)으로 직접 입력. strip_tags()로 내용이 완전히 비어있으면 오류 처리.

💡  HTML 태그를 활용하여 메일 내용을 풍부하게 꾸밀 수 있습니다. <b>굵게</b>, <a href="...">링크</a>, <img src="..."> 등 표준 HTML 사용 가능. 단, 수신 메일 클라이언트에 따라 CSS 스타일이 제한될 수 있으므로 인라인 스타일을 권장합니다.

2.3 발송 처리 흐름

1. 클라이언트 검증: 제목•내용 빈 값 체크 (JavaScript confirmSend() 함수)
2. 서버 CSRF 토큰 검증
3. DxMailer 클래스 존재 여부 확인
4. 수신자 목록 수집 (to_type에 따라 custom/all/role 분기)
5. 각 이메일에 filter_var(FILTER_VALIDATE_EMAIL) 유효성 검증 → 통과한 것만 수신자 리스트에 추가
6. 유효한 수신자가 없으면 "유효한 수신자가 없습니다." 오류
7. 수신자별 DxMailer::message()→to()→subject()→html()→send() 순서로 개별 발송
8. 10명 초과 시 건당 10ms 지연 처리
9. 성공/실패 수 집계 후 결과 메시지 표시

발송 결과 메시지 유형:

메시지 색상	조건 및 내용
초록 (success)	실패 0건. "발송 완료: 성공 N건"
노랑 (warning)	성공과 실패가 모두 있음. "발송 완료: 성공 N건, 실패 M건 — 실패 이메일 목록(최대 3개 표시)"
빨강 (error)	전체 실패(성공 0건). 상세 오류 메시지와 실패한 이메일 표시.

3. SMTP 설정 탭

외부 SMTP 서버를 사용하여 메일을 발송하는 경우 이 탭에서 설정합니다. SMTP는 선택 사항이며, Linux 서버의 mail() 함수가 정상 동작한다면 설정하지 않아도 됩니다.

💡  SMTP를 사용하는 이유: 발신자 도메인 인증(SPF•DKIM), 스팸 분류 방지, 대용량 발송 시 전송률 개선, Gmail•네이버 등 특정 서비스 이용이 필요한 경우.

3.1 SMTP 설정 필드 전체 설명

필드	DB 저장 키	설명 및 예시
SMTP 호스트	smtp_host	SMTP 서버 주소. 예: smtp.gmail.com, smtp.naver.com, email-smtp.ap-northeast-2.amazonaws.com.
포트	smtp_port	587(STARTTLS, 권장), 465(SSL/TLS), 25(비암호화), 2525(대안). 포트 변경 시 암호화 방식이 자동으로 연동 변경됩니다.
암호화	smtp_encryption	STARTTLS(tls), SSL/TLS(ssl), 없음(none). 포트 587→STARTTLS, 465→SSL, 25→없음으로 자동 설정.
사용자명	smtp_user	SMTP 로그인 이메일 또는 사용자명. Gmail이면 Gmail 주소, SendGrid이면 "apikey".
비밀번호	smtp_pass	SMTP 비밀번호 또는 앱 비밀번호. 비워두면 기존 저장 비밀번호가 유지됩니다. "저장됨" 초록 아이콘으로 설정 여부 확인 가능.
발신자 이름	smtp_from_name	메일 발신자 이름으로 표시되는 텍스트. 예: "사이트명 관리자", "DXCMS".
발신자 이메일	smtp_from_email	발신 이메일 주소. 수신자가 발신자로 보는 주소. 예: noreply@yourdomain.com.

3.2 SMTP 저장 처리

1. CSRF 토큰 검증
2. smtp_host, smtp_port, smtp_encryption, smtp_user, smtp_from_email, smtp_from_name 6개 필드 저장
3. smtp_pass: 입력값이 빈 문자열이 아닐 때만 저장 (빈 값이면 기존 비밀번호 유지)
4. settings 테이블에 ON DUPLICATE KEY UPDATE 방식으로 UPSERT
5. DxCache::flush() + DxMailer::flushCache()로 캐시 초기화
6. "SMTP 설정이 저장되었습니다." 성공 메시지와 함께 SMTP 탭 유지

3.3 SMTP 포트/암호화 자동 연동

포트 드롭다운 변경 시 JavaScript로 암호화 방식이 자동으로 변경됩니다.
 

포트 선택	암호화 자동 변경	주 용도
587	STARTTLS	가장 일반적. Gmail·네이버·Outlook·SendGrid 기본 권장 포트.
465	SSL/TLS	Gmail SSL, 다음(카카오). 일부 서비스의 대안 포트.
25	없음	비암호화. 내부 서버 전용. 외부 인터넷 발송에는 대부분 차단됨.
2525	STARTTLS	25포트 차단 환경의 대안 포트. 일부 클라우드 호스팅에서 사용.

4. SMTP 테스트 발송

SMTP 설정이 저장된 경우(smtp_host 값 존재) SMTP 설정 탭 하단에 테스트 발송 영역이 표시됩니다.

4.1 테스트 발송 방법

1. SMTP 설정 탭 이동
2. SMTP 설정 저장 (smtp_host 등 입력 후 [설정 저장] 클릭)
3. 테스트 발송 영역의 [수신 이메일] 필드 확인 (기본값: smtp_user 값)
4. 수신 이메일을 변경하려면 직접 입력
5. [테스트 발송] 버튼 클릭
6. 성공 메시지 또는 오류 메시지 확인
7. SMTP 통신 로그(디버그 패널)에서 서버 응답 코드 확인

4.2 SMTP 통신 로그 읽는 법

테스트 발송 후 어두운 배경의 SMTP 통신 로그 패널이 표시됩니다. 색상으로 명령/응답을 구분합니다.
 

색상	접두사	의미
하늘색	>>> (발신)	클라이언트(DXCMS)가 SMTP 서버로 보내는 명령. EHLO, AUTH, MAIL FROM, RCPT TO, DATA 등.
초록	<< 2xx/3xx	SMTP 서버의 성공/중간 응답. 220(준비), 250(OK), 334(인증 요청), 354(데이터 시작).
빨강	<< 4xx/5xx	SMTP 서버의 오류 응답. 4xx: 일시적 오류(재시도 가능), 5xx: 영구 오류(설정 문제).
회색	기타	연결 시도, SSL 핸드쉐이크 등 내부 상태 정보.

4.3 주요 SMTP 오류 코드 및 해결법

오류 코드	의미	해결 방법
535	인증 실패	사용자명 또는 비밀번호가 잘못됨. Gmail은 앱 비밀번호 필요. 2단계 인증 확인.
554	발신 거부	발신 IP 또는 도메인이 스팸으로 분류됨. SPF/DKIM 설정, AWS SES 사용 고려.
Connection refused	연결 불가	SMTP 호스트 주소나 포트가 잘못됨. 방화벽에서 해당 포트(587/465)가 차단됨.
Connection timeout	연결 시간 초과	서버에서 외부 SMTP 연결이 차단됨. 호스팅사 방화벽 규칙 확인. 대안 포트(2525) 시도.
SSL/TLS 오류	암호화 협상 실패	포트와 암호화 방식이 불일치. 465→SSL, 587→STARTTLS 조합 확인.

5. SMTP 서비스별 설정 참고표

주요 메일 서비스의 SMTP 설정값을 안내합니다. 관리자 화면 SMTP 설정 탭 하단에도 동일한 참고표가 내장되어 있습니다.
 

서비스	SMTP 호스트	포트	암호화	비고	권장
Gmail	smtp.gmail.com	587	STARTTLS	앱 비밀번호 필요 (2단계 인증)	★★★
Gmail SSL	smtp.gmail.com	465	SSL	앱 비밀번호 필요	★★
네이버	smtp.naver.com	587	STARTTLS	네이버 비밀번호	★★★
다음(카카오)	smtp.daum.net	465	SSL		★★
네이버 Works	smtp.worksmobile.com	587	STARTTLS	네이버 Works 계정	★★
Outlook/365	smtp.office365.com	587	STARTTLS	MS 계정 또는 앱 비밀번호	★★★
AWS SES	email-smtp.ap-northeast-2.amazonaws.com	587	STARTTLS	SES SMTP 자격증명 별도 생성	★★★
SendGrid	smtp.sendgrid.net	587	STARTTLS	사용자명: apikey / PW: API 키	★★★
Mailgun	smtp.mailgun.org	587	STARTTLS	Mailgun 계정 자격증명	★★★

5.1 Gmail 앱 비밀번호 설정 방법

Gmail을 SMTP로 사용하려면 Google 계정에서 앱 비밀번호를 별도로 발급해야 합니다. 일반 Gmail 비밀번호로는 연결이 거부됩니다.

1. Google 계정 보안 페이지 접속 (myaccount.google.com/security)
2. "2단계 인증" 활성화 (미활성화 상태라면 먼저 설정)
3. "앱 비밀번호" 메뉴 접속 (myaccount.google.com/apppasswords)
4. "앱 선택" → "기타(맞춤 이름)" 선택 → 이름 입력(예: DXCMS) → [생성]
5. 생성된 16자리 앱 비밀번호 복사
6. DXCMS SMTP 설정의 [비밀번호] 필드에 복사한 앱 비밀번호 붙여넣기

⚠️  앱 비밀번호는 생성 시 한 번만 표시됩니다. 반드시 저장 전에 복사하세요. 분실 시 새로 생성해야 합니다.

6. 환경 정보 탭

[환경 정보] 탭은 서버의 메일 발송 환경을 자동 감지하여 드라이버별 사용 가능 여부와 현재 선택된 드라이버를 시각적으로 보여줍니다.

6.1 드라이버 자동 감지 결과 패널

각 드라이버가 색상과 배지로 상태를 표시합니다.
 

표시 색상	배지	의미
보라색 배경	사용 중	현재 메일 발송에 사용 중인 드라이버. 보라색 행 강조.
초록 배경	사용 가능	사용할 수 있는 상태이나 현재 선택되지 않은 드라이버.
회색	불가	서버 환경에서 사용 불가능한 드라이버. 관련 함수가 비활성화되었거나 조건 미충족.

6.2 서버 환경 정보 항목

PHP 버전	현재 서버에서 실행 중인 PHP 버전.
운영체제	서버 OS 이름과 커널 정보 (PHP_OS + php_uname("s")).
웹서버	Apache, Nginx 등 웹서버 소프트웨어 정보 ($_SERVER["SERVER_SOFTWARE"]).
mail() 함수	PHP mail() 함수 활성화 여부. disable_functions에 mail이 포함되어 있으면 ❌ 비활성화.
fsockopen()	TCP 소켓 연결 함수. SMTP 드라이버가 사용. 비활성화 시 SMTP 사용 불가.
popen()	프로세스 열기 함수. sendmail 드라이버가 사용.
sendmail 경로	php.ini의 sendmail_path 설정값.
SMTP 설정	smtp_host 설정 여부. ✅ 설정됨 / ○ 미설정.
선택된 드라이버	현재 자동 선택된 드라이버 ID(smtp/mail/sendmail) 또는 "없음".

6.3 커스텀 드라이버 등록 (개발자)

dx_mailer_drivers 훅으로 AWS SES API•Mailchimp 등 커스텀 드라이버를 플러그인으로 등록할 수 있습니다.
 

DxMailer::registerDriver()	드라이버 ID, 클래스명, 파일 경로, 최우선 적용 여부(true=1순위 강제 선택)를 인자로 받습니다.
DxMailDriverInterface	모든 드라이버가 구현해야 하는 인터페이스. getName(), getDescription(), isAvailable(), getError(), send(DxMailMessage $msg) 메서드 필요.
최우선 적용 옵션	registerDriver() 4번째 인자를 true로 설정하면 SMTP보다도 높은 우선순위로 선택됩니다.

7. 전체 사용 절차

7.1 처음 설정 시 절차 (SMTP 사용 시)

1. 관리자 대시보드 → [메일 보내기] 메뉴 클릭
2. [환경 정보] 탭에서 현재 드라이버 상태 확인
3. 드라이버가 없으면 → [SMTP 설정] 탭 이동
4. 사용할 SMTP 서비스의 호스트•포트•암호화•사용자명•비밀번호•발신자 이름•이메일 입력
5. [설정 저장] 클릭
6. [테스트 발송] 영역에서 수신 이메일 확인 후 [테스트 발송] 클릭
7. 성공 메시지 및 SMTP 통신 로그 확인
8. 테스트 성공 후 [메일 보내기] 탭으로 이동하여 실제 발송

7.2 메일 발송 절차

1. [메일 보내기] 탭 클릭
2. 상단 드라이버 배지에서 발송 가능 여부 확인 (ACTIVE 배지가 표시되어야 함)
3. 수신자 선택: 직접 입력 / 전체 회원 / 권한별 중 하나 선택
4. 수신자 방식에 따른 추가 설정 (이메일 직접 입력 또는 권한 선택)
5. 메일 제목 입력 (필수)
6. 메일 내용 입력 (HTML 태그 사용 가능, 필수)
7. [메일 발송] 버튼 클릭
8. 확인 창(전체/권한별 발송 시)에서 확인
9. 발송 결과 메시지 확인 (성공 N건 / 실패 M건)

8. 자주 묻는 질문 (FAQ)

Q1. 메일 발송 버튼이 비활성화되어 있습니다.

A. 사용 가능한 메일 드라이버가 없는 상태입니다. 다음을 확인하세요: ① [환경 정보] 탭에서 드라이버 감지 결과 확인. ② mail() 함수가 활성화되어 있는지 확인(서버 php.ini의 disable_functions 항목). ③ SMTP 설정이 없다면 [SMTP 설정] 탭에서 외부 SMTP 서버를 설정하세요.

Q2. Gmail SMTP 연결이 실패합니다.

A. Gmail은 일반 비밀번호로 SMTP 연결이 불가능합니다. Google 계정에서 2단계 인증을 활성화하고 앱 비밀번호(16자리)를 발급하여 [비밀번호] 필드에 입력하세요. 포트 587 + STARTTLS 조합을 권장합니다.

Q3. 발송은 되는데 스팸 메일로 분류됩니다.

A. mail() 함수 발송 시 SPF/DKIM 설정이 없으면 스팸으로 분류되기 쉽습니다. 다음을 시도하세요: ① AWS SES, SendGrid, Mailgun 등 전문 메일 발송 서비스 SMTP 사용. ② 도메인의 SPF/DKIM/DMARC DNS 레코드 설정. ③ 발신자 이메일을 사이트 도메인과 일치시키기(noreply@yourdomain.com).

Q4. 전체 회원 발송 중 일부가 실패합니다.

A. 발송 결과 메시지에 실패한 이메일 주소가 표시됩니다(최대 3개). 주요 원인: ① 수신자 메일함이 가득 찬 경우. ② 수신자 도메인의 스팸 필터에 차단된 경우. ③ SMTP 서버의 시간당 발송 한도 초과. 한도 초과 시 잠시 후 재시도하거나 발송 속도를 낮추는 설정이 필요합니다.

Q5. SMTP 설정이 저장되었는데 환경 정보에서 SMTP가 "불가"로 표시됩니다.

A. fsockopen() 함수가 비활성화되어 있거나 서버 방화벽에서 외부 SMTP 포트(587/465)로의 outbound 연결이 차단된 것입니다. [환경 정보] 탭의 fsockopen() 항목을 확인하세요. 호스팅 환경에서는 관리자에게 해당 포트 개방을 요청하세요.

Q6. 메일 내용에 이미지를 첨부하고 싶습니다.

A. 현재 관리자 메일 보내기 화면에서 파일 첨부 기능은 제공되지 않습니다. 내용 입력 시 공개된 외부 이미지 URL을 <img src="https://..." alt=""> 태그로 삽입하는 방식을 사용하세요. 이미지는 외부 서버에 호스팅되어야 합니다.

Q7. 메일 발송 내역을 확인할 수 있나요?

A. 현재 버전에서는 발송 내역 로그 기능이 없습니다. 발송 결과(성공/실패 수)만 화면에 표시됩니다. 발송 기록이 필요하다면 서버의 메일 로그(/var/log/mail.log 등)를 확인하거나, AWS SES•SendGrid 등의 서비스에서 제공하는 대시보드를 활용하세요.

9. 용어 정리

용어	설명
DxMailer	DXCMS 메일 발송 핵심 클래스. 드라이버 자동 감지·선택, 메시지 빌더, 발송 처리를 담당.
DxMailDriverInterface	메일 드라이버 인터페이스. getName/getDescription/isAvailable/getError/send 메서드 정의.
DxMailMessage	메일 메시지 객체. to/subject/html/text/from/attachment 등 메서드로 구성.
DxSmtpDriver	SMTP 드라이버 클래스. fsockopen()으로 TCP 소켓 연결 후 SMTP 프로토콜 직접 구현.
DxMailFuncDriver	PHP mail() 함수를 사용하는 드라이버 클래스.
DxSendmailDriver	popen()으로 sendmail 바이너리를 직접 실행하는 드라이버 클래스.
smtp_host	settings 테이블에 저장되는 SMTP 서버 주소 설정 키.
smtp_port	SMTP 접속 포트. 587(STARTTLS), 465(SSL), 25(비암호화).
smtp_encryption	SMTP 암호화 방식. tls(STARTTLS)/ssl(SSL/TLS)/none.
smtp_user	SMTP 로그인 사용자명(이메일 또는 ID).
smtp_pass	SMTP 비밀번호 또는 앱 비밀번호.
smtp_from_email	발신자 이메일 주소. 수신자에게 보이는 발신 주소.
smtp_from_name	발신자 이름. 메일 클라이언트에서 보이는 발신자 표시명.
to_type	발송 대상 유형. custom(직접 입력)/all(전체 회원)/role(권한별).
to_role	권한별 발송 시 대상 권한. member/manager/admin.
DxMailer::detect()	서버 환경을 감지하여 사용 가능한 드라이버 목록과 선택된 드라이버를 반환하는 메서드.
DxMailer::message()	DxMailMessage 객체를 생성하는 정적 팩토리 메서드.
DxMailer::send()	DxMailMessage를 선택된 드라이버로 발송하는 메서드.
DxMailer::testSmtp()	SMTP 설정값으로 테스트 메일을 발송하고 통신 로그를 반환하는 메서드.
DxMailer::flushCache()	드라이버 감지 캐시를 초기화하는 메서드.
앱 비밀번호	Google 등에서 2단계 인증 계정에 제3자 앱 접근을 허용하기 위해 발급하는 16자리 전용 비밀번호.
STARTTLS	일반 연결로 시작 후 TLS 암호화로 업그레이드하는 방식. 포트 587 사용.
SPF/DKIM	메일 발신 도메인 인증 DNS 레코드. 스팸 분류 방지에 효과적.