The Transactional API lets you send templated emails directly from your application code — perfect for welcome emails, password resets, order confirmations, and notifications.
Transactional vs Marketing Emails
| Type | Use Case | Trigger |
|---|---|---|
| Transactional | Password reset, order confirmation | User action |
| Marketing | Newsletter, promotions | Campaign schedule |
Transactional emails typically have 2-3x higher open rates because users expect and need them.
API Endpoint
POST https://your-maillayer-domain.com/api/transactional/send
Authentication
Each template has its own API key. No additional headers needed — just include the key in the request body.
Request Format
| Parameter | Type | Required | Description |
|---|---|---|---|
apiKey | string | Yes | Template API key |
to | string | Yes | Recipient email |
variables | object | No | Template variables |
Step 1: Create a Template
- Open your Maillayer dashboard
- Go to Transactional in the sidebar
- Click Create Template
- Design your email using the editor
- Add variables using
{{variableName}}syntax - Save and publish
Example template with variables:
Hi {{firstName}},
Your order #{{orderNumber}} has been confirmed.
Delivery estimate: {{deliveryDate}}
Thanks for shopping with us!
Step 2: Get Your API Key
After saving your template:
- Click on the template
- Copy the API Key shown (looks like
txn_67f21b6001f510a2a8c87574_m958x7up)
Each template has a unique key — this ensures you can't accidentally send the wrong template.
Step 3: Send Emails
Basic Request (cURL)
curl -X POST "https://your-domain.com/api/transactional/send" \
-H "Content-Type: application/json" \
-d '{
"apiKey": "txn_67f21b6001f510a2a8c87574_m958x7up",
"to": "user@example.com",
"variables": {}
}'
With Variables (cURL)
curl -X POST "https://your-domain.com/api/transactional/send" \
-H "Content-Type: application/json" \
-d '{
"apiKey": "txn_67f21b6001f510a2a8c87574_m958x7up",
"to": "john@example.com",
"variables": {
"firstName": "John",
"orderNumber": "ORD-12345",
"deliveryDate": "January 10, 2025"
}
}'
Code Examples
JavaScript (Node.js)
const sendEmail = async (to, variables) => {
const response = await fetch('https://your-domain.com/api/transactional/send', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
apiKey: 'txn_67f21b6001f510a2a8c87574_m958x7up',
to,
variables
})
});
return response.json();
};
// Usage
await sendEmail('user@example.com', {
firstName: 'John',
resetLink: 'https://app.example.com/reset?token=abc123'
});
Python
import requests
def send_email(to: str, variables: dict):
response = requests.post(
'https://your-domain.com/api/transactional/send',
json={
'apiKey': 'txn_67f21b6001f510a2a8c87574_m958x7up',
'to': to,
'variables': variables
}
)
return response.json()
# Usage
send_email('user@example.com', {
'firstName': 'John',
'orderNumber': 'ORD-12345'
})
PHP
function sendEmail($to, $variables) {
$ch = curl_init('https://your-domain.com/api/transactional/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'apiKey' => 'txn_67f21b6001f510a2a8c87574_m958x7up',
'to' => $to,
'variables' => $variables
])
]);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Usage
sendEmail('user@example.com', [
'firstName' => 'John',
'verificationCode' => '123456'
]);
Response Format
Success (200)
{
"success": true,
"messageId": "0102018d3f5e7a8b-1234abcd-5678-90ef-ghij-klmnopqrstuv-000000"
}
Error (4xx)
{
"success": false,
"error": "Invalid API key"
}
Common Use Cases
Welcome Email
await sendEmail(newUser.email, {
firstName: newUser.name,
loginUrl: 'https://app.example.com/login'
});
Password Reset
await sendEmail(user.email, {
resetLink: `https://app.example.com/reset?token=${token}`,
expiresIn: '24 hours'
});
Order Confirmation
await sendEmail(order.customerEmail, {
orderNumber: order.id,
orderTotal: order.total,
itemCount: order.items.length,
estimatedDelivery: order.deliveryDate
});
Rate Limits
Rate limits depend on your email provider:
Amazon SES
- Sandbox: 1 email/second, 200/day
- Production: 14+ emails/second (increases with reputation)
SendGrid
- Free tier: 100 emails/day
- Paid plans: varies by tier
Mailgun
- Free tier: 5,000 emails/month
- Paid plans: varies by tier
For high-volume sending, consider queuing emails on your side.
Troubleshooting
"Invalid API key"
- Verify you copied the complete key
- Check the template is published (not draft)
Email not received
- Check spam folder
- Verify recipient address is correct
- If using Amazon SES sandbox mode, recipient must be verified in SES
Variables not replaced
- Variable names are case-sensitive
- Ensure variable names match exactly:
{{firstName}}needsfirstNamein variables object
Next: Tracking & Analytics — Monitor email engagement and metrics
Previous: Segments — Target specific audience groups
