Send Email API

Send emails to specific recipients, contacts, tags, segments, or all contacts. Supports both template-based and custom HTML content with optional scheduling.

Endpoint

POST /api/v1/messages/send

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json

Quick Examples

Simplest: Direct Email

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "direct_email",
    "direct_email": "user@example.com",
    "template_key": "welcome-email",
    "variables": {
      "name": "John"
    }
  }'

To Existing Contact

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "contact",
    "contact_external_id": "user-123",
    "template_key": "order-confirmation",
    "variables": {
      "order_id": "ORD-456"
    }
  }'

Request Parameters

Required Fields

Field	Type	Description
`recipient_type`	string	How to target recipients: `direct_email`, `contact`, `tag`, `segment`, `all`

Recipient-Specific Fields

Recipient Type	Required Field	Type	Description
`direct_email`	`direct_email`	string	Email address to send to
`contact`	`contact_external_id`	string	External ID of the contact
`tag`	`tags`	string[]	Array of tags to match
`segment`	`segment_id`	string	Segment ID from dashboard
`all`	(none)	-	Sends to all active contacts

Optional Fields for Direct Email

Field	Type	Description
`direct_first_name`	string	Recipient's first name (for personalization)
`direct_last_name`	string	Recipient's last name (for personalization)

Content Options (Choose One)

Option	Required Fields	Description
Template	`template_key`	Use a pre-created template
Custom HTML	`subject` + `content`	Provide your own HTML

Common Optional Fields

Field	Type	Description
`variables`	object	Template variables (key-value pairs)
`from_email`	string	Override sender email address
`from_name`	string	Override sender name
`reply_to`	string	Reply-to email address
`metadata`	object	Custom tracking data
`trigger_at`	string	ISO 8601 UTC timestamp for scheduled send

Complete Request Examples

1. Send Direct Email with Template

Send to a specific email address without requiring a contact record:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "direct_email",
    "direct_email": "imashok02@gmail.com",
    "direct_first_name": "John",
    "direct_last_name": "Doe",
    "template_key": "verify-api-otp",
    "variables": {
      "company": "Acme Corp",
      "OTP_CODE": 123456
    }
  }'

Response:

{
  "success": true,
  "trigger_id": "211e62ab-2ddf-4032-9305-561fc6eb2102",
  "job_id": "10",
  "message": "Email queued successfully"
}

Use Cases:

OTP verification emails
One-time notifications
Emails to non-registered users
Quick transactional emails

2. Send to All Contacts

Broadcast to all active contacts in your database:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "welcome-box",
    "recipient_type": "all",
    "variables": {
      "title": "Excuse me",
      "message": "Yeah this is default message",
      "my_company": "Awesome Company"
    },
    "from_email": "custom@example.com",
    "from_name": "Custom Sender"
  }'

Response:

{
  "success": true,
  "trigger_id": "f3c8d4e2-5a91-4b72-9e67-8d4f3c2a1b0e",
  "job_id": "11",
  "message": "Email queued successfully"
}

Use Cases:

Company-wide announcements
System maintenance notifications
Major product launches
Emergency communications

3. Send to All Contacts (Scheduled)

Schedule a broadcast for future delivery:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "welcome-box",
    "recipient_type": "all",
    "variables": {
      "title": "Excuse me",
      "message": "Yeah this is default message",
      "my_company": "Awesome Company"
    },
    "from_email": "custom@example.com",
    "from_name": "Custom Sender",
    "trigger_at": "2025-03-15T10:00:00Z"
  }'

Response:

{
  "success": true,
  "trigger_id": "a5b6c7d8-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "job_id": "12",
  "message": "Email scheduled successfully"
}

Use Cases:

Newsletter scheduling
Time-zone optimized sends
Planned announcements
Event reminders

Note: The trigger_at field accepts ISO 8601 UTC timestamps. The email will be queued and sent at the specified time.

4. Send to Contacts with Tags

Target specific audience segments using tags:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "welcome-box",
    "recipient_type": "tag",
    "tags": [
      "sms",
      "beta"
    ],
    "variables": {
      "title": "Excuse me",
      "message": "Yeah this is default message",
      "my_company": "Awesome Company"
    },
    "from_email": "custom@example.com",
    "from_name": "Custom Sender"
  }'

Response:

{
  "success": true,
  "trigger_id": "c7d8e9f0-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
  "job_id": "13",
  "message": "Email queued successfully"
}

Use Cases:

Marketing campaigns to specific segments
Feature announcements to beta users
Targeted promotions
Customer tier-based communications

5. Send to Tags (Scheduled)

Schedule a campaign to tagged contacts:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "welcome-box",
    "recipient_type": "tag",
    "tags": [
      "sms",
      "beta"
    ],
    "variables": {
      "title": "Excuse me",
      "message": "Yeah this is default message",
      "my_company": "Awesome Company"
    },
    "from_email": "custom@example.com",
    "from_name": "Custom Sender",
    "trigger_at": "2025-03-20T14:30:00Z"
  }'

Response:

{
  "success": true,
  "trigger_id": "d8e9f0a1-3b4c-5d6e-7f8a-9b0c1d2e3f4g",
  "job_id": "14",
  "message": "Email scheduled successfully"
}

Use Cases:

Pre-scheduled campaigns
Drip campaign sequences
Time-zone specific sends
Event-based follow-ups

6. Send to a Contact

Send to a specific contact by their external ID:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "welcome-box",
    "recipient_type": "contact",
    "contact_external_id": "b4abc345-a761-4a02-bcec-3f5532e39efc",
    "variables": {
      "title": "Excuse me",
      "message": "Yeah this is default message",
      "my_company": "Awesome Company"
    },
    "from_email": "custom@example.com",
    "from_name": "Custom Sender"
  }'

Response:

{
  "success": true,
  "trigger_id": "e9f0a1b2-4c5d-6e7f-8a9b-0c1d2e3f4g5h",
  "job_id": "15",
  "message": "Email queued successfully"
}

Use Cases:

Personalized transactional emails
Order confirmations
Account notifications
User-specific updates

Auto-populated Variables: When sending to a contact, their data is automatically available:

{{contact_first_name}} - Contact's first name
{{contact_last_name}} - Contact's last name
{{contact_email}} - Contact's email
{{contact_external_id}} - Contact's external ID

7. Send to a Segment

Send to a dynamic segment created in the dashboard:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "welcome-box",
    "recipient_type": "segment",
    "segment_id": "20c8eba1-d55d-4fdf-8b26-42780142f10e",
    "variables": {
      "title": "Excuse me",
      "message": "Yeah this is default message",
      "my_company": "Awesome Company"
    },
    "from_email": "custom@example.com",
    "from_name": "Custom Sender"
  }'

Response:

{
  "success": true,
  "trigger_id": "f0a1b2c3-5d6e-7f8a-9b0c-1d2e3f4g5h6i",
  "job_id": "16",
  "message": "Email queued successfully"
}

Use Cases:

Advanced audience targeting
Behavioral-based campaigns
Custom filtered audiences
Dynamic list management

Note: Segments are created in the Sendmator dashboard and allow you to filter contacts based on:

Custom fields
Behavioral data
Engagement metrics
Complex conditions

8. Send to Contact (Scheduled)

Schedule an email to a specific contact:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "welcome-box",
    "recipient_type": "contact",
    "contact_external_id": "b4abc345-a761-4a02-bcec-3f5532e39efc",
    "variables": {
      "title": "Excuse me",
      "message": "Yeah this is default message",
      "my_company": "Awesome Company"
    },
    "from_email": "custom@example.com",
    "from_name": "Custom Sender",
    "trigger_at": "2025-03-25T09:00:00Z"
  }'

Response:

{
  "success": true,
  "trigger_id": "a1b2c3d4-6e7f-8a9b-0c1d-2e3f4g5h6i7j",
  "job_id": "17",
  "message": "Email scheduled successfully"
}

Use Cases:

Appointment reminders
Follow-up sequences
Birthday/anniversary emails
Time-delayed notifications

Custom HTML Content (Without Template)

You can send emails with custom HTML instead of using templates:

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "direct_email",
    "direct_email": "user@example.com",
    "subject": "Welcome to Our Platform",
    "content": "<h1>Welcome!</h1><p>Thanks for signing up, we are excited to have you.</p>",
    "plain_text_content": "Welcome! Thanks for signing up.",
    "from_email": "hello@company.com",
    "from_name": "Company Team"
  }'

Response:

{
  "success": true,
  "trigger_id": "b2c3d4e5-7f8a-9b0c-1d2e-3f4g5h6i7j8k",
  "job_id": "18",
  "message": "Email queued successfully"
}

Use Cases:

Quick one-off emails
Dynamic content generation
A/B testing variations
Custom branded emails

Response Format

Success Response (200 OK)

{
  "success": true,
  "trigger_id": "211e62ab-2ddf-4032-9305-561fc6eb2102",
  "job_id": "10",
  "message": "Email queued successfully"
}

Field	Type	Description
`success`	boolean	Always `true` for successful requests
`trigger_id`	string	Unique ID to track this send operation
`job_id`	string	Job queue ID for monitoring
`message`	string	Human-readable status message

Error Responses

Invalid Recipient Type (400)

{
  "statusCode": 400,
  "message": "Invalid recipient type",
  "error": "Bad Request"
}

Missing Required Field (400)

{
  "statusCode": 400,
  "message": "direct_email is required when recipient_type is 'direct_email'",
  "error": "Bad Request"
}

Contact Not Found (404)

{
  "statusCode": 404,
  "message": "Contact with external_id 'user-123' not found",
  "error": "Not Found"
}

Template Not Found (404)

{
  "statusCode": 404,
  "message": "Template with key 'welcome-email' not found",
  "error": "Not Found"
}

Insufficient Wallet Balance (400)

{
  "statusCode": 400,
  "message": "Insufficient wallet balance. Required: 10.50 USD, Available: 5.00 USD. Please recharge your wallet to continue.",
  "error": "Bad Request"
}

Recipient Types Summary

Type	Description	Required Field	Use Case
`direct_email`	Send to specific email	`direct_email`	OTPs, one-time notifications
`contact`	Send to existing contact	`contact_external_id`	Personalized emails
`tag`	Send to tagged contacts	`tags` (array)	Marketing campaigns
`segment`	Send to dynamic segment	`segment_id`	Advanced targeting
`all`	Send to all contacts	(none)	Broadcasts

Scheduling

Schedule emails for future delivery using ISO 8601 UTC timestamps:

{
  "trigger_at": "2025-03-15T10:00:00Z"
}

Examples:

Specific date/time: "2025-03-15T10:00:00Z"
Midnight UTC: "2025-03-20T00:00:00Z"
Afternoon UTC: "2025-03-25T14:30:00Z"

Notes:

All times must be in UTC timezone
Format must be ISO 8601
Minimum scheduling time: 1 minute in the future
Maximum scheduling time: 1 year in the future

Variables & Personalization

Custom Variables

Pass any key-value pairs in the variables object:

{
  "variables": {
    "name": "John",
    "company": "Acme Corp",
    "order_id": "ORD-123",
    "discount": "20%"
  }
}

Use in templates: {{name}}, {{company}}, {{order_id}}, {{discount}}

Auto-Populated Contact Variables

When using recipient_type: "contact", contact data is automatically available:

Variable	Description
`{{contact_first_name}}`	Contact's first name
`{{contact_last_name}}`	Contact's last name
`{{contact_email}}`	Contact's email address
`{{contact_external_id}}`	Contact's external ID

Direct Email Variables

When using recipient_type: "direct_email" with direct_first_name and direct_last_name:

{
  "recipient_type": "direct_email",
  "direct_email": "user@example.com",
  "direct_first_name": "John",
  "direct_last_name": "Doe"
}

These become available as:

{{direct_first_name}} → "John"
{{direct_last_name}} → "Doe"
{{direct_email}} → "user@example.com"

Custom Sender

Override the default sender for specific use cases:

{
  "from_email": "sales@company.com",
  "from_name": "Sales Team"
}

Common Use Cases:

Department-specific emails (sales@, support@, billing@)
Personal sender names (account manager)
Brand-specific campaigns
Event-specific communications

Important: The from_email must be verified in your Sendmator account.

Best Practices

1. Choose the Right Recipient Type

# ✅ Good: Use direct_email for one-off sends
{
  "recipient_type": "direct_email",
  "direct_email": "user@example.com"
}

# ✅ Good: Use contact for registered users
{
  "recipient_type": "contact",
  "contact_external_id": "user-123"
}

# ❌ Avoid: Creating contacts just to send one email

2. Use Templates for Consistency

# ✅ Good: Templates ensure brand consistency
{
  "template_key": "welcome-email",
  "variables": { "name": "John" }
}

# ⚠️ OK but harder to maintain: Inline HTML
{
  "subject": "Welcome",
  "content": "<h1>Welcome John</h1>"
}

3. Test Before Sending to All

# Step 1: Test with yourself first
{
  "recipient_type": "direct_email",
  "direct_email": "your-email@company.com",
  "template_key": "newsletter"
}

# Step 2: Send to small test group
{
  "recipient_type": "tag",
  "tags": ["internal-team"]
}

# Step 3: Send to everyone
{
  "recipient_type": "all"
}

4. Use Scheduling for Better Engagement

# Send at optimal times for your audience
{
  "recipient_type": "all",
  "template_key": "newsletter",
  "trigger_at": "2025-03-15T14:00:00Z"  # 2 PM UTC = 9 AM EST
}

5. Add Meaningful Metadata

{
  "metadata": {
    "campaign_id": "q1-2025-launch",
    "source": "web-signup",
    "user_segment": "premium",
    "ab_test_variant": "A"
  }
}

Use metadata for:

Campaign tracking
A/B test identification
Attribution analysis
Custom analytics

Code Examples

cURL

curl -X POST https://api.sendmator.com/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_type": "direct_email",
    "direct_email": "user@example.com",
    "template_key": "welcome",
    "variables": { "name": "John" }
  }'

Python

import requests

response = requests.post(
    'https://api.sendmator.com/api/v1/messages/send',
    headers={
        'X-API-Key': 'sk_live_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'recipient_type': 'direct_email',
        'direct_email': 'user@example.com',
        'template_key': 'welcome',
        'variables': {'name': 'John'}
    }
)

print(response.json())

PHP

<?php
$ch = curl_init('https://api.sendmator.com/api/v1/messages/send');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: sk_live_your_api_key',
    'Content-Type: application/json'
]);

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'recipient_type' => 'direct_email',
    'direct_email' => 'user@example.com',
    'template_key' => 'welcome',
    'variables' => ['name' => 'John']
]));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response));
?>

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "recipient_type": "direct_email",
        "direct_email":   "user@example.com",
        "template_key":   "welcome",
        "variables":      map[string]string{"name": "John"},
    }

    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.sendmator.com/api/v1/messages/send", bytes.NewBuffer(jsonData))
    req.Header.Set("X-API-Key", "sk_live_your_api_key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.sendmator.com/api/v1/messages/send')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['X-API-Key'] = 'sk_live_your_api_key'
request['Content-Type'] = 'application/json'
request.body = {
  recipient_type: 'direct_email',
  direct_email: 'user@example.com',
  template_key: 'welcome',
  variables: { name: 'John' }
}.to_json

response = http.request(request)
puts response.body

Rate Limits

Plan	Emails/Month	API Calls/Minute
Free	1,000	10
Pro	100,000	100
Plus	500,000	500
Enterprise	Custom	Custom

Next Steps

Node.js SDK - Use our official SDK for easier integration
Create Templates - Set up reusable email templates
Manage Contacts - Build your contact database
Track Status - Monitor email delivery status
API Overview - Explore other endpoints

Endpoint​

Headers​

Quick Examples​

Simplest: Direct Email​

To Existing Contact​

Request Parameters​

Required Fields​

Recipient-Specific Fields​

Optional Fields for Direct Email​

Content Options (Choose One)​

Common Optional Fields​

Complete Request Examples​

1. Send Direct Email with Template​

2. Send to All Contacts​

3. Send to All Contacts (Scheduled)​

4. Send to Contacts with Tags​

5. Send to Tags (Scheduled)​

6. Send to a Contact​

7. Send to a Segment​

8. Send to Contact (Scheduled)​

Custom HTML Content (Without Template)​

Response Format​

Success Response (200 OK)​

Error Responses​

Invalid Recipient Type (400)​

Missing Required Field (400)​

Contact Not Found (404)​

Template Not Found (404)​

Insufficient Wallet Balance (400)​

Recipient Types Summary​

Scheduling​

Variables & Personalization​

Custom Variables​

Auto-Populated Contact Variables​

Direct Email Variables​

Custom Sender​

Best Practices​

1. Choose the Right Recipient Type​

2. Use Templates for Consistency​

3. Test Before Sending to All​

4. Use Scheduling for Better Engagement​

5. Add Meaningful Metadata​

Code Examples​

cURL​

Python​

PHP​

Go​

Ruby​

Rate Limits​

Next Steps​

Endpoint

Headers

Quick Examples

Simplest: Direct Email

To Existing Contact

Request Parameters

Required Fields

Recipient-Specific Fields

Optional Fields for Direct Email

Content Options (Choose One)

Common Optional Fields

Complete Request Examples

1. Send Direct Email with Template

2. Send to All Contacts

3. Send to All Contacts (Scheduled)

4. Send to Contacts with Tags

5. Send to Tags (Scheduled)

6. Send to a Contact

7. Send to a Segment

8. Send to Contact (Scheduled)

Custom HTML Content (Without Template)

Response Format

Success Response (200 OK)

Error Responses

Invalid Recipient Type (400)

Missing Required Field (400)

Contact Not Found (404)

Template Not Found (404)

Insufficient Wallet Balance (400)

Recipient Types Summary

Scheduling

Variables & Personalization

Custom Variables

Auto-Populated Contact Variables

Direct Email Variables

Custom Sender

Best Practices

1. Choose the Right Recipient Type

2. Use Templates for Consistency

3. Test Before Sending to All

4. Use Scheduling for Better Engagement

5. Add Meaningful Metadata

Code Examples

cURL

Python

PHP

Go

Ruby

Rate Limits

Next Steps