필요 권한: mail
POST
/api/v1/mail/send
단건 이메일을 즉시 발송합니다. 사용자의 기본 SMTP provider를 통해 발송됩니다.
Request Body
{
"to": "user@example.com",
"subject": "Order Confirmation",
"html": "<h1>Your order has been confirmed</h1>",
"text": "Your order has been confirmed",
"from_email": "support@yourdomain.com",
"from_name": "Your App",
"reply_to": "reply@yourdomain.com",
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"],
"tags": ["order", "confirmation"],
"metadata": {"order_id": "12345"}
}Parameters
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | 수신자 이메일 |
subject | string | Yes | 이메일 제목 |
html | string | Yes* | HTML 본문 (*html 또는 text 중 하나 필수) |
text | string | Yes* | 텍스트 본문 |
from_email | string | No | 발신자 이메일 (기본: SMTP provider 설정) |
from_name | string | No | 발신자 이름 |
reply_to | string | No | 회신 주소 |
cc | array | No | 참조 이메일 목록 |
bcc | array | No | 숨은참조 이메일 목록 |
tags | array | No | 이메일 태그 (분류용) |
metadata | object | No | 사용자 정의 메타데이터 |
Response
{
"success": true,
"data": {
"message_id": "<abc123.1706600000@mailpass.im>",
"status": "sent",
"to": "user@example.com",
"from": "support@yourdomain.com"
}
}
POST
/api/v1/mail/send-batch
다건 이메일을 큐에 추가합니다. 최대 100건까지 가능하며, Cron에 의해 처리됩니다.
Request Body
{
"messages": [
{"to": "a@example.com", "subject": "Hello A", "html": "<p>Hi A</p>"},
{"to": "b@example.com", "subject": "Hello B", "html": "<p>Hi B</p>"}
],
"from_email": "support@yourdomain.com",
"from_name": "Your App"
}Response
{
"success": true,
"data": {
"total": 2,
"queued": 2,
"failed": 0,
"messages": [
{"to": "a@example.com", "status": "queued", "queue_id": 101},
{"to": "b@example.com", "status": "queued", "queue_id": 102}
]
}
}
GET
/api/v1/mail/status/{message_id}
발송된 이메일의 상태 및 추적 이벤트를 조회합니다.
Response
{
"success": true,
"data": {
"message": {
"message_id": "<abc123@mailpass.im>",
"from_email": "support@yourdomain.com",
"to_email": "user@example.com",
"subject": "Order Confirmation",
"status": "sent",
"error_message": null,
"sent_at": "2026-01-30T12:00:00",
"created_at": "2026-01-30T12:00:00"
},
"events": [
{
"event_type": "open",
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0...",
"created_at": "2026-01-30T12:05:00"
}
]
}
}Error Codes
| Code | HTTP | Description |
|---|---|---|
VALIDATION_ERROR | 400 | 필수 필드 누락 또는 유효하지 않은 이메일 |
NO_SMTP_PROVIDER | 422 | 기본 SMTP provider가 설정되지 않음 |
SEND_LIMIT_EXCEEDED | 429 | SMTP provider 일별/시간별 발송 한도 초과 |
SEND_FAILED | 500 | 이메일 발송 실패 |
사용 예제
cURL
# Single send
curl -X POST https://dev.mailpass.im/api/v1/mail/send \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "user@example.com",
"subject": "Hello",
"html": "<p>Hello World</p>"
}'
# Batch send
curl -X POST https://dev.mailpass.im/api/v1/mail/send-batch \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"to": "a@example.com", "subject": "Hi A", "html": "<p>Hello A</p>"},
{"to": "b@example.com", "subject": "Hi B", "html": "<p>Hello B</p>"}
],
"from_email": "support@yourdomain.com"
}'
# Check status
curl https://dev.mailpass.im/api/v1/mail/status/MESSAGE_ID \
-H "Authorization: Bearer YOUR_API_KEY"JavaScript (fetch)
// Single send
const response = await fetch('https://dev.mailpass.im/api/v1/mail/send', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: 'user@example.com',
subject: 'Hello',
html: '<p>Hello World</p>'
})
});
const data = await response.json();
console.log(data.data.message_id);PHP SDK
$client = new MailPass\Client('mp_live_YOUR_KEY');
// Single send
$result = $client->mail->send([
'to' => 'user@example.com',
'subject' => 'Hello',
'html' => '<p>Hello World</p>',
]);
echo $result['data']['message_id'];SMTP Provider 설정 필요
Mail Send API를 사용하려면 먼저 대시보드 > SMTP 설정에서 SMTP provider를 추가하고 기본값으로 설정해야 합니다. MailPass 자체 SMTP 또는 Amazon SES, SendGrid, Mailgun 등을 지원합니다.