REST APIEmail

Email Endpoints

Send emails, verification codes (OTP), and transactional messages via the REST API.

POST/api/email/send

Send Email

Send an email to one or more recipients. Supports HTML content, attachments, CC/BCC, and templates.

Request Body

FieldTypeRequiredDescription
fromstringYesSender email (or "Name <email>")
recipientsstring[]YesArray of recipient email addresses
subjectstringYesEmail subject line
contentstringConditionalHTML email content (required if no templateId)
templateIdstringNoTemplate ID to use instead of content
variablesobjectNoTemplate variables for substitution
ccstring[]NoCC recipients
bccstring[]NoBCC recipients
replyTostringNoReply-to email address
attachmentsarrayNoFile 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/send

Send 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

FieldTypeRequiredDescription
tostringYesRecipient email address
fromstringYesSender email address
codestringYesThe OTP code to send
appNamestringNoApplication name (default: "Metigan")
expiresInMinutesnumberNoCode expiration time in minutes
subjectstringNoCustom email subject
templateIdstringNoCustom OTP template ID
idempotencyKeystringNoKey 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:

VariableDescription
{{code}}The OTP code
{{appName}}Your application name
{{expiresInMinutes}}Expiration time in minutes
POST/api/transactional/send

Send 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

FieldTypeRequiredDescription
tostringYesRecipient email address
fromstringYesSender email address
subjectstringYesEmail subject line
contentstringConditionalHTML email content (required if no templateId)
templateIdstringNoTemplate ID to use
variablesobjectNoTemplate variables
replyTostringNoReply-to email address
idempotencyKeystringNoKey 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:

ErrorStatusDescription
INVALID_EMAIL422Invalid email address format
MISSING_REQUIRED_FIELD400Required field is missing
TEMPLATE_NOT_FOUND404Template ID not found
ATTACHMENT_TOO_LARGE400Attachment exceeds 7MB limit
RATE_LIMIT_EXCEEDED429Too many requests
QUOTA_EXCEEDED403Email quota exceeded for your plan
SENDER_NOT_VERIFIED403Sender 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);