Mailer Service

The Mailer Service handles transactional email sending for your application. Send password resets, order confirmations, welcome emails, and more using your own email provider (Mailgun or SendGrid). The service includes template management with Handlebars support and detailed delivery tracking.

What you can do:

  • Send transactional emails with HTML and plain text content
  • Create and manage reusable email templates with Handlebars
  • Configure multiple email providers (Mailgun, SendGrid)
  • Track email delivery with logs and statistics
  • Preview templates with sample data before sending

Interactive API Reference

For complete API documentation with interactive testing, visit our Swagger UI where you can try all endpoints with your own credentials.

View Interactive API Docs

Important: Before sending emails, you must configure an email provider (Mailgun or SendGrid) with your API credentials. You can do this through the API or in your dashboard.

Send an Email

Send transactional emails directly with HTML/text content or using a pre-built template. Perfect for password resets, order confirmations, welcome emails, and notifications. You can provide raw HTML/text or reference a template with dynamic data. 

curl -X POST https://mailer.stackfordevs.com/v1/emails/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to YourApp",
    "html": "
Welcome!
Thanks for signing up.
",
    "text": "Welcome! Thanks for signing up.",
    "from": "noreply@yourapp.com"
  }'

Required Fields:

  • to - Recipient email address
  • subject - Email subject line

Choose one:

  • html + text - Raw email content
  • templateId + templateData - Use a template

Send Email with Template

Use a pre-built template to send consistent, branded emails. Templates support Handlebars syntax for dynamic content like user names, order numbers, or custom variables. This keeps your email code clean and makes it easy to update email designs without changing application code. 

curl -X POST https://mailer.stackfordevs.com/v1/emails/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "to": "user@example.com",
    "subject": "Password Reset Request",
    "templateId": "tmpl_abc123",
    "templateData": {
      "userName": "John Doe",
      "resetLink": "https://yourapp.com/reset?token=xyz"
    }
  }'

Tip: Create templates first using the template endpoints below, then reference them by ID when sending emails. Template data is merged with Handlebars variables.

Create Email Template

Build reusable email templates with Handlebars syntax for dynamic content. Templates can include variables like {{userName}} or {{orderNumber}} that get replaced with actual values when sending. Perfect for password resets, receipts, and notification emails. 

curl -X POST https://mailer.stackfordevs.com/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "name": "Password Reset",
    "templateKey": "password-reset",
    "subject": "Reset Your Password",
    "html": "
Hi {{userName}}
Click here to reset your password.
",
    "text": "Hi {{userName}}, click this link to reset your password: {{resetLink}}"
  }'

Template Variables (Handlebars):

  • {{variable}} - Simple variable replacement
  • {{#if condition}}...{{/if}} - Conditional content
  • {{#each items}}...{{/each}} - Loop through arrays

List Email Templates

Retrieve all email templates for your project. Useful for displaying template options in your admin dashboard or selecting which template to use when sending emails. 

curl -X GET https://mailer.stackfordevs.com/v1/templates \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Preview Template

Test how a template will look with actual data before sending it to users. This renders the Handlebars variables with your sample data and returns the final HTML, so you can verify formatting and content. 

curl -X POST https://mailer.stackfordevs.com/v1/templates/tmpl_abc123/preview \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "data": {
      "userName": "Jane Doe",
      "resetLink": "https://example.com/reset?token=test"
    }
  }'

Response: Returns the rendered HTML and text with all variables replaced. Use this to preview templates in your admin dashboard.

View Email Logs

Track email delivery and troubleshoot issues by viewing all sent emails. You can get logs for a specific recipient or view all emails sent from your project. Each log includes delivery status, timestamps, and error details if delivery failed.

Get all email logs:
curl -X GET "https://mailer.stackfordevs.com/v1/logs?limit=50&offset=0" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"
Get logs for specific recipient:
curl -X GET https://mailer.stackfordevs.com/v1/emails/logs/user@example.com \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Email Statistics

Get aggregated statistics about your email sending—total sent, delivery rates, failed sends, and more. Use this to monitor email health and identify delivery issues. 

curl -X GET https://mailer.stackfordevs.com/v1/stats \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID"

Configure Email Provider

Set up Mailgun or SendGrid as your email delivery provider. You can configure multiple providers and set one as default. The Mailer Service uses your provider credentials to send emails, giving you full control over deliverability and sender reputation. 

curl -X POST https://mailer.stackfordevs.com/v1/providers \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "name": "My Mailgun Account",
    "type": "mailgun",
    "config": {
      "apiKey": "your-mailgun-api-key",
      "domain": "mg.yourdomain.com"
    },
    "isDefault": true
  }'

Supported Providers:

  • Mailgun: Requires apiKey and domain
  • SendGrid: Requires apiKey

Test Email Provider

After configuring a provider, send a test email to verify your credentials and configuration are correct. This helps catch issues before sending emails to real users. 

curl -X POST https://mailer.stackfordevs.com/v1/providers/prv_abc123/test \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -H "x-tenant-id: YOUR_TENANT_ID" \
  -H "x-project-id: YOUR_PROJECT_ID" \
  -d '{
    "to": "your-email@example.com"
  }'

Error Codes

The Mailer API uses standard HTTP status codes.

Status Description
200 Success - Email sent or request completed
201 Created - Template or provider created
204 No Content - Resource deleted successfully
400 Bad Request - Invalid email format or missing required fields
401 Unauthorized - Missing or invalid API keys
404 Not Found - Template or provider doesn't exist
500 Server Error - Email sending failed or provider error