REST APIEmail
Email Endpoints
Send emails, verification codes (OTP), and transactional messages via the REST API.
POST
/api/email/sendSend Email
Send an email to one or more recipients. Supports HTML content, attachments, CC/BCC, and templates.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Sender email (or "Name <email>") |
recipients | string[] | Yes | Array of recipient email addresses |
subject | string | Yes | Email subject line |
content | string | Conditional | HTML email content (required if no templateId) |
templateId | string | No | Template ID to use instead of content |
variables | object | No | Template variables for substitution |
cc | string[] | No | CC recipients |
bcc | string[] | No | BCC recipients |
replyTo | string | No | Reply-to email address |
attachments | array | No | File attachments (base64 encoded) |
Example Request
curlTerminal
1
2
3
4
5
6
7
8
9
10
curl -X POST https://api.metigan.com/api/email/send \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Company <noreply@yourcompany.com>",
"recipients": ["user@example.com", "another@example.com"],
"subject": "Welcome to Our Platform!",
"content": "<h1>Welcome!</h1><p>Thank you for joining us.</p>",
"replyTo": "support@yourcompany.com"
}'Example with Template
curlTerminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X POST https://api.metigan.com/api/email/send \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Company <noreply@yourcompany.com>",
"recipients": ["user@example.com"],
"subject": "Welcome, {{firstName}}!",
"templateId": "welcome-template-id",
"variables": {
"firstName": "John",
"lastName": "Doe",
"accountUrl": "https://app.yourcompany.com/dashboard"
}
}'Example with Attachments
curlTerminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -X POST https://api.metigan.com/api/email/send \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"from": "billing@yourcompany.com",
"recipients": ["customer@example.com"],
"subject": "Your Invoice #INV-2024-001",
"content": "<p>Please find your invoice attached.</p>",
"attachments": [
{
"content": "JVBERi0xLjQK...(base64 encoded)",
"filename": "invoice.pdf",
"contentType": "application/pdf"
}
]
}'Response
200 OKJSON
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"success": true,
"message": "Email sent successfully",
"successfulEmails": [
{
"recipient": "user@example.com",
"trackingId": "mtg-1705678234567-0001"
}
],
"failedEmails": [],
"recipientCount": 1,
"emailsRemaining": 9999
}POST
/api/otp/sendSend OTP
Send a One-Time Password (OTP) verification email. OTP emails are sent through a priority fast lane with built-in rate limiting to prevent abuse.
Priority Delivery
OTP emails are processed with higher priority than regular emails to ensure quick delivery of time-sensitive verification codes.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient email address |
from | string | Yes | Sender email address |
code | string | Yes | The OTP code to send |
appName | string | No | Application name (default: "Metigan") |
expiresInMinutes | number | No | Code expiration time in minutes |
subject | string | No | Custom email subject |
templateId | string | No | Custom OTP template ID |
idempotencyKey | string | No | Key to prevent duplicate sends |
Example Request
curlTerminal
1
2
3
4
5
6
7
8
9
10
curl -X POST https://api.metigan.com/api/otp/send \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"to": "user@example.com",
"from": "security@yourapp.com",
"code": "847291",
"appName": "YourApp",
"expiresInMinutes": 10
}'Response
200 OKJSON
1
2
3
4
5
6
7
{
"success": true,
"message": "OTP email sent successfully",
"trackingId": "mtg-1705678234567-otp",
"emailId": "email_abc123xyz",
"queued": false
}Template Variables
If using a custom template, these variables are automatically available:
| Variable | Description |
|---|---|
{{code}} | The OTP code |
{{appName}} | Your application name |
{{expiresInMinutes}} | Expiration time in minutes |
POST
/api/transactional/sendSend Transactional Email
Send time-sensitive transactional emails like password resets, order confirmations, receipts, and other critical notifications. These emails are processed with priority delivery.
Use Cases
- Password reset emails
- Order confirmations
- Payment receipts
- Shipping notifications
- Account notifications
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient email address |
from | string | Yes | Sender email address |
subject | string | Yes | Email subject line |
content | string | Conditional | HTML email content (required if no templateId) |
templateId | string | No | Template ID to use |
variables | object | No | Template variables |
replyTo | string | No | Reply-to email address |
idempotencyKey | string | No | Key to prevent duplicate sends |
Password Reset Example
curlTerminal
1
2
3
4
5
6
7
8
9
curl -X POST https://api.metigan.com/api/transactional/send \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"to": "user@example.com",
"from": "security@yourapp.com",
"subject": "Reset Your Password",
"content": "<h1>Password Reset</h1><p>Click <a href="https://yourapp.com/reset?token=abc123">here</a> to reset your password.</p><p>This link expires in 1 hour.</p>"
}'Order Confirmation Example
curlTerminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -X POST https://api.metigan.com/api/transactional/send \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"to": "customer@example.com",
"from": "orders@yourshop.com",
"subject": "Order Confirmed #ORD-12345",
"templateId": "order-confirmation-template",
"variables": {
"orderId": "ORD-12345",
"customerName": "John Doe",
"orderTotal": "$99.99",
"orderItems": [
{"name": "Product A", "qty": 2, "price": "$49.99"},
{"name": "Product B", "qty": 1, "price": "$50.00"}
],
"trackingUrl": "https://yourshop.com/track/ORD-12345"
}
}'Response
200 OKJSON
1
2
3
4
5
6
7
{
"success": true,
"message": "Transactional email sent successfully",
"trackingId": "mtg-1705678234567-txn",
"emailId": "email_xyz789abc",
"queued": false
}Error Codes
Common error responses for email endpoints:
| Error | Status | Description |
|---|---|---|
INVALID_EMAIL | 422 | Invalid email address format |
MISSING_REQUIRED_FIELD | 400 | Required field is missing |
TEMPLATE_NOT_FOUND | 404 | Template ID not found |
ATTACHMENT_TOO_LARGE | 400 | Attachment exceeds 7MB limit |
RATE_LIMIT_EXCEEDED | 429 | Too many requests |
QUOTA_EXCEEDED | 403 | Email quota exceeded for your plan |
SENDER_NOT_VERIFIED | 403 | Sender domain not verified |
Error Response Example
422 Unprocessable EntityJSON
1
2
3
4
5
6
{
"success": false,
"error": "INVALID_EMAIL",
"message": "Invalid email address format: user@invalid",
"field": "recipients[0]"
}Code Examples
JavaScript (fetch)
send-email.jsJavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const response = await fetch('https://api.metigan.com/api/email/send', {
method: 'POST',
headers: {
'x-api-key': 'your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
from: 'Your Company <noreply@yourcompany.com>',
recipients: ['user@example.com'],
subject: 'Welcome!',
content: '<h1>Welcome!</h1><p>Thank you for signing up.</p>'
})
});
const result = await response.json();
console.log(result);Python (requests)
send_email.pyPython
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import requests
response = requests.post(
'https://api.metigan.com/api/email/send',
headers={
'x-api-key': 'your_api_key',
'Content-Type': 'application/json'
},
json={
'from': 'Your Company <noreply@yourcompany.com>',
'recipients': ['user@example.com'],
'subject': 'Welcome!',
'content': '<h1>Welcome!</h1><p>Thank you for signing up.</p>'
}
)
result = response.json()
print(result)PHP (cURL)
send-email.phpPhp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?php
$ch = curl_init('https://api.metigan.com/api/email/send');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'x-api-key: your_api_key',
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode([
'from' => 'Your Company <noreply@yourcompany.com>',
'recipients' => ['user@example.com'],
'subject' => 'Welcome!',
'content' => '<h1>Welcome!</h1><p>Thank you for signing up.</p>'
])
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
print_r($result);