Transactional Email API
Integrate high-speed email delivery into your application in minutes.
01. Authentication
All requests must include your secret server key. Keep this key secure and never expose it in client-side code.
// Set these headers in your HTTP client (e.g., Guzzle, Axios, or cURL) Content-Type: application/json X-Server-API-Key: your_secret_api_key_here
02. API Endpoint
Send all POST requests to the following production URL:
https://postalmail.mailsafi.com/api/v1/send/message
03. JSON Payload Structure
The to field expects an array of strings, even if sending to a single recipient.
{
"to": ["recipient@example.com"], // Array of recipient emails
"from": "hello@yourdomain.com", // Must be a verified domain in Postal Mail
"subject": "Account Update",
"plain_body": "Hello, your account has been updated.",
"html_body": "<h1>Hello</h1><p>Your account has been updated.</p>", // Optional HTML version
"attachments": [ // Optional: Base64 encoded files
{
"name": "update.pdf",
"content_type": "application/pdf",
"data": "JVBERi0xLjQKJcfs..."
}
]
}
04. Implementation Example (cURL)
curl -X POST https://postalmail.mailsafi.com/api/v1/send/message \
-H "Content-Type: application/json" \
-H "X-Server-API-Key: YOUR_API_KEY" \
-d '{
"to": ["user@example.com"],
"from": "system@yourdomain.com",
"subject": "Platform Alert",
"plain_body": "This is a test notification from M@ilSafi."
}'
05. Response Codes
| Code | Meaning | Developer Note |
|---|---|---|
200 OK |
Success | Message queued for delivery successfully. |
401 |
Unauthorized | Check if X-Server-API-Key is valid. |
422 |
Validation Error | Usually missing a required field like 'to' or 'from'. |
