Send Message

The Send Message endpoint is your one-stop solution for all email sending needs. It handles single emails, bulk sending, contact targeting, and everything in between - all asynchronously for optimal performance.

Endpoint

POST /api/v1/messages/send

Headers

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

Why Use This Endpoint?

🚀 Handles Everything - Single emails, bulk, contact targeting, template/inline content
⚡ Asynchronous Processing - Never wait for large sends to complete
🎯 Smart Targeting - Send to specific contacts, tags, or all contacts
🔄 Auto-Variables - Contact data automatically injected as contact_* variables
📊 Built-in Tracking - Email opens, clicks, replies, and delivery status
💪 Scalable - Handles 1 email or 100,000 emails efficiently
✉️ Custom Sender - Override from email and name per message
⚡ Smart Priority - Automatic prioritization based on template type (transactional vs promotional)

Core Concept

Choose your recipient type and we handle the rest:

Recipient Type	Description	Use Case
`contact`	Send to one specific contact	Welcome emails, notifications
`tag`	Send to all contacts with a tag	Segment campaigns, announcements
`all`	Send to all your active contacts	Company-wide updates, newsletters

Request Structure

Required Fields

Field	Type	Description
`recipient_type`	enum	`contact`, `tag`, or `all`

Conditional Fields (Based on Recipient Type)

Recipient Type	Required Field	Description
`contact`	`contact_external_id`	External ID of the specific contact
`tag`	`tag`	Tag name to filter contacts
`all`	(none)	Sends to all active contacts

Content (Choose One)

Option	Fields	Description
Template	`template_key`	Use a pre-created template by key
Inline Content	`subject` + `content`	Write content directly in the request

Optional Fields

Field	Type	Description
`subject`	string	Email subject line (can include variables)
`content`	string	HTML email content (can include variables)
`variables`	object	Custom variables (merged with contact data)
`attachment_ids`	array	File IDs to attach
`from_email`	string	Custom sender email address
`from_name`	string	Custom sender name

Template Types & Send Priority

When using templates, Sendmator automatically determines the email type and priority based on your template configuration. This ensures optimal delivery and proper categorization.

Email Types

Templates are categorized into two types:

Type	Description	Priority	Use Cases
Transactional	Critical user-triggered emails	High	Password resets, order confirmations, account notifications, receipts
Promotional	Marketing and campaign emails	Standard	Newsletters, product announcements, marketing campaigns

How It Works

Template Configuration: When you create a template, you specify whether it's transactional or promotional
Automatic Priority: The system automatically assigns send priority based on the template type
Delivery Optimization: Transactional emails are prioritized in the queue for faster delivery

Priority Levels

High Priority (Transactional):
- Processed immediately
- Optimized for fastest delivery
- Typically delivered within seconds
- Examples: Password resets, 2FA codes, purchase confirmations
Standard Priority (Promotional):
- Processed in order with rate limiting
- Optimized for deliverability and reputation
- Respects user preferences and unsubscribe lists
- Examples: Weekly newsletters, feature announcements, special offers

Important Notes

Template type is set when creating the template and cannot be changed per-request
Transactional emails have higher deliverability as they're expected by recipients
Promotional emails must comply with CAN-SPAM and GDPR regulations
Choose the correct template type to ensure proper categorization and compliance

Example: Using a Transactional Template

{
  "template_key": "password-reset",  // This template is marked as "transactional"
  "recipient_type": "contact",
  "contact_external_id": "user_12345"
  // High priority automatically applied
}

Example: Using a Promotional Template

{
  "template_key": "weekly-newsletter",  // This template is marked as "promotional"
  "recipient_type": "tag",
  "tag": "newsletter_subscribers"
  // Standard priority automatically applied
}

Use Case 1: Single Contact Email with Template

Send a personalized email to one specific contact using a template:

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",
    "subject": "Welcome to hello",
    "content": "",
    "variables": {
        "title": "Excuse me",
        "message": "Yeah this is default message",
        "my_company": "Awesome Company"
    },
    "attachment_ids": [],
    "from_email": "custom@example.com",
    "from_name": "Custom Sender"
  }'

Response:

{
    "success": true,
    "trigger_id": "4de498b5-49d3-4f90-ab45-4054e75f2e3f",
    "job_id": "12",
    "message": "Email queued successfully"
}

Auto-populated variables from contact:

{{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 from your database

Use Case 2: Inline Content (No Template)

Send an email with inline HTML content:

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": "CRM_USER_12345",
    "subject": "Welcome {{contact_first_name}}!",
    "content": "<h1>Welcome {{contact_first_name}} {{contact_last_name}}!</h1><p>Thanks for joining us. Your account is ready!</p><p>Get started: <a href=\"{{onboarding_url}}\">Setup Guide</a></p><p>Your account ID: {{contact_external_id}}</p>",
    "variables": {
      "onboarding_url": "https://app.company.com/onboarding"
    },
    "from_email": "welcome@company.com",
    "from_name": "Company Welcome Team"
  }'

Response:

{
    "success": true,
    "trigger_id": "7fa398c2-1d4e-4b90-bc56-5064f86f3a4g",
    "job_id": "13",
    "message": "Email queued successfully"
}

Use Case 3: Tag-Based Campaign

Send to all contacts with a specific tag:

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": "tag",
    "tag": "premium_customers",
    "subject": "{{announcement_title}} - Exclusive for Premium Members",
    "content": "<h1>Hi {{contact_first_name}}!</h1><p>As a premium member, you get early access to {{feature_name}}.</p><p>We will reach out to {{contact_email}} this week with more details.</p><ul><li>{{benefit_1}}</li><li>{{benefit_2}}</li><li>{{benefit_3}}</li></ul>",
    "variables": {
      "announcement_title": "New AI Features Available",
      "feature_name": "AI Assistant Pro",
      "benefit_1": "Priority support queue",
      "benefit_2": "Advanced analytics dashboard",
      "benefit_3": "Custom integration options"
    },
    "from_email": "announcements@company.com",
    "from_name": "Product Team"
  }'

Response:

{
    "success": true,
    "trigger_id": "9bc298d3-2e5f-5c91-cd67-6175g97h4b5i",
    "job_id": "14",
    "message": "Email queued successfully"
}

Use Case 4: Company-Wide Announcement

Send to all active 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 '{
    "recipient_type": "all",
    "subject": "Important Update from {{company_name}}",
    "content": "<h1>Important Update</h1><p>Hi {{contact_first_name}},</p><p>We wanted to inform you about {{update_type}} that affects all our customers.</p><p><strong>What this means for you:</strong></p><p>{{impact_description}}</p><p>Questions? Reply to this email at {{contact_email}} and we will get back to you.</p>",
    "variables": {
      "company_name": "TechCorp",
      "update_type": "a security enhancement",
      "impact_description": "Your data will be even more secure with our new encryption standards."
    },
    "from_email": "updates@techcorp.com",
    "from_name": "TechCorp Team"
  }'

Response:

{
    "success": true,
    "trigger_id": "1cd409e4-3f6g-6d02-de78-7286h08i5c6j",
    "job_id": "15",
    "message": "Email queued successfully"
}

Use Case 5: Using Templates with Custom Variables

Use pre-created templates for consistent branding:

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": "tag",
    "tag": "trial_users",
    "template_key": "trial-conversion-reminder",
    "subject": "",
    "content": "",
    "variables": {
      "trial_end_date": "2024-02-29",
      "discount_amount": "25%",
      "upgrade_deadline": "2024-02-25"
    },
    "from_email": "sales@company.com",
    "from_name": "Sales Team"
  }'

Response:

{
    "success": true,
    "trigger_id": "2de510f5-4g7h-7e13-ef89-8397i19j6d7k",
    "job_id": "16",
    "message": "Email queued successfully"
}

Response Format

Success Response (200 OK)

{
  "success": true,
  "trigger_id": "4de498b5-49d3-4f90-ab45-4054e75f2e3f",
  "job_id": "12",
  "message": "Email queued successfully"
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`trigger_id`	string	Unique ID to track this specific trigger
`job_id`	string	Job ID for tracking the email sending job
`message`	string	Human-readable status message

Auto-Populated Contact Variables

When sending to contacts, their data becomes available as variables:

Available Variables

{{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 (the ID from your database)

Example Contact:

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@techstart.com",
  "external_id": "USER_12345"
}

Example Usage in Template:

<h1>Hi {{contact_first_name}} {{contact_last_name}}!</h1>
<p>We're reaching out to {{contact_email}} regarding your account.</p>
<p>Your user ID: {{contact_external_id}}</p>

Variable Priority

Variables merge with this priority (highest to lowest):

Custom variables (your variables object)
Contact variables (auto-populated contact_*)
Template defaults (if using templates)

Example:

{
  "variables": {
    "special_offer": "30% off",
    "company_name": "Awesome Company"
  }
}

Your custom variables can be used alongside contact variables in your templates.

Custom Sender Options

Default Behavior

If from_email and from_name are not provided, emails are sent from your configured default sender address.

Custom Sender

Override the sender information per message:

{
  "from_email": "custom@example.com",
  "from_name": "Custom Sender"
}

Use Cases for Custom Sender:

Department-specific emails (sales@, support@, billing@)
Personalized sender names (e.g., account manager name)
Brand-specific campaigns
Reply-to routing

Error Responses

Contact Not Found (404)

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

No Recipients for Tag (404)

{
  "statusCode": 404,
  "message": "No active contacts found with tag 'nonexistent_tag'",
  "error": "Not Found"
}

Invalid Recipient Type (400)

{
  "statusCode": 400,
  "message": [
    "recipient_type must be one of: contact, tag, all"
  ],
  "error": "Bad Request"
}

Missing Required Field (400)

{
  "statusCode": 400,
  "message": [
    "contact_external_id is required when recipient_type is 'contact'"
  ],
  "error": "Bad Request"
}

Template Not Found (404)

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

Invalid From Email (400)

{
  "statusCode": 400,
  "message": [
    "from_email must be a valid email address"
  ],
  "error": "Bad Request"
}

Performance & Limits

Volume Handling

Single contact: Processed immediately
Tag filtering: Up to 50,000 contacts
All contacts: Up to 100,000 contacts
Larger volumes: Contact support for enterprise limits

Processing Speed

Transactional Emails:

Processed with high priority
Typically delivered within seconds
No batching delays

Promotional Emails:

Small jobs (< 1,000): 2-5 minutes
Medium jobs (1,000-10,000): 5-15 minutes
Large jobs (10,000+): 15-60 minutes

Rate Limiting

Jobs are processed based on your plan:

Free: 1,000 emails/month
Pro: 100,000 emails/month
Enterprise: Custom limits

Best Practices

1. Use Meaningful Tags

# Good: Descriptive, hierarchical tags
"premium_customers"
"trial_day_7"
"enterprise_northeast"
"churned_last_30_days"

# Avoid: Generic tags
"group1"
"list"
"users"

2. Populate Contact Data

Ensure your contacts have complete information for better personalization:

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "external_id": "USER_12345"
}

3. Test Before Sending

# Test with a single contact first
{
  "recipient_type": "contact",
  "contact_external_id": "TEST_USER_ME",
  "subject": "Test: {{contact_first_name}}",
  "content": "<p>Testing variables: Hi {{contact_first_name}} {{contact_last_name}}!</p>"
}

4. Use Templates for Consistency

Create reusable templates for:

Transactional emails (receipts, confirmations)
Marketing campaigns
Automated drip sequences
Team-specific communications

5. Choose the Right Template Type

Set the correct template type when creating templates:

Use Transactional for:

Password resets and account security
Order confirmations and receipts
Account notifications (login alerts, etc.)
Time-sensitive user actions
Any critical, user-triggered emails

Use Promotional for:

Marketing campaigns and newsletters
Product announcements
Special offers and discounts
General company updates
Non-critical communications

Choosing the correct type ensures:

Proper send priority
Better deliverability
Compliance with email regulations
Accurate analytics and reporting

6. Monitor Job Status

Save the job_id from the response to track:

Processing status
Delivery rates
Engagement metrics

Complete Example: Product Launch Campaign

Here's a comprehensive example for a product launch:

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": "product-launch-announcement",
    "recipient_type": "tag",
    "tag": "active_customers",
    "subject": "🚀 {{product_name}} is here, {{contact_first_name}}!",
    "content": "",
    "variables": {
      "product_name": "AI Assistant Pro",
      "feature_1": "Smart email suggestions",
      "feature_2": "Advanced automation rules",
      "feature_3": "Real-time collaboration",
      "discount_amount": "25%",
      "activation_link": "https://app.company.com/features/ai-assistant",
      "company_name": "TechCorp"
    },
    "attachment_ids": [
      "file_feature_guide_789"
    ],
    "from_email": "product@techcorp.com",
    "from_name": "TechCorp Product Team"
  }'

Response:

{
    "success": true,
    "trigger_id": "4de498b5-49d3-4f90-ab45-4054e75f2e3f",
    "job_id": "18",
    "message": "Email queued successfully"
}

This single endpoint handles all your email sending needs - from welcome emails to massive campaigns! 🚀

Next Steps

Manage Contacts - Create and organize your contact database
Email Templates Guide - Create reusable templates
Sending Emails Guide - Best practices and examples
API Overview - Explore other API endpoints

Endpoint​

Headers​

Why Use This Endpoint?​

Core Concept​

Request Structure​

Required Fields​

Conditional Fields (Based on Recipient Type)​

Content (Choose One)​

Optional Fields​

Template Types & Send Priority​

Email Types​

How It Works​

Priority Levels​

Important Notes​

Use Case 1: Single Contact Email with Template​

Use Case 2: Inline Content (No Template)​

Use Case 3: Tag-Based Campaign​

Use Case 4: Company-Wide Announcement​

Use Case 5: Using Templates with Custom Variables​

Response Format​

Success Response (200 OK)​

Response Fields​

Auto-Populated Contact Variables​

Available Variables​

Variable Priority​

Custom Sender Options​

Default Behavior​

Custom Sender​

Error Responses​

Contact Not Found (404)​

No Recipients for Tag (404)​

Invalid Recipient Type (400)​

Missing Required Field (400)​

Template Not Found (404)​

Invalid From Email (400)​

Performance & Limits​

Volume Handling​

Processing Speed​

Rate Limiting​

Best Practices​

1. Use Meaningful Tags​

2. Populate Contact Data​

3. Test Before Sending​

4. Use Templates for Consistency​

5. Choose the Right Template Type​

6. Monitor Job Status​

Complete Example: Product Launch Campaign​

Next Steps​

Endpoint

Headers

Why Use This Endpoint?

Core Concept

Request Structure

Required Fields

Conditional Fields (Based on Recipient Type)

Content (Choose One)

Optional Fields

Template Types & Send Priority

Email Types

How It Works

Priority Levels

Important Notes

Use Case 1: Single Contact Email with Template

Use Case 2: Inline Content (No Template)

Use Case 3: Tag-Based Campaign

Use Case 4: Company-Wide Announcement

Use Case 5: Using Templates with Custom Variables

Response Format

Success Response (200 OK)

Response Fields

Auto-Populated Contact Variables

Available Variables

Variable Priority

Custom Sender Options

Default Behavior

Custom Sender

Error Responses

Contact Not Found (404)

No Recipients for Tag (404)

Invalid Recipient Type (400)

Missing Required Field (400)

Template Not Found (404)

Invalid From Email (400)

Performance & Limits

Volume Handling

Processing Speed

Rate Limiting

Best Practices

1. Use Meaningful Tags

2. Populate Contact Data

3. Test Before Sending

4. Use Templates for Consistency

5. Choose the Right Template Type

6. Monitor Job Status

Complete Example: Product Launch Campaign

Next Steps