Sending Emails

Learn how to send emails through Mailtura

Mailtura provides multiple ways to send emails, from simple transactional messages to complex templated campaigns.

Overview

You can send emails through Mailtura using:

  • API: Send emails programmatically via REST API
  • UI: Send and manage emails through the web dashboard

Choose the method that best fits your workflow. Most production applications use the API, while the UI is ideal for testing and one-off campaigns.

Quick Start

Send a simple email:

curl -X POST https://your-mailtura-instance.com/api/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello from Mailtura",
    "html": "<p>This is a test email</p>",
    "text": "This is a test email"
  }'

Using Templates

Send an email using a template:

curl -X POST https://your-mailtura-instance.com/api/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "template": "welcome-email",
    "variables": {
      "firstName": "John",
      "companyName": "Acme Corp"
    }
  }'

Email Parameters

Required Fields

  • to: Recipient email address (string or array)
  • subject: Email subject (if not using template)

Optional Fields

  • from: Sender email (defaults to tenant settings)
  • fromName: Sender name
  • replyTo: Reply-to address
  • cc: CC recipients (array)
  • bcc: BCC recipients (array)
  • attachments: File attachments (array)
  • tags: Custom tags for filtering (array)
  • metadata: Custom metadata (object)

Advanced Features

Multiple Recipients

Send to multiple recipients:

{
  "to": ["user1@example.com", "user2@example.com"],
  "subject": "Team Update",
  "template": "team-update"
}

Attachments

Include file attachments:

{
  "to": "user@example.com",
  "subject": "Your Invoice",
  "template": "invoice",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "base64-encoded-content",
      "contentType": "application/pdf"
    }
  ]
}

Custom Headers

Add custom email headers:

{
  "to": "user@example.com",
  "subject": "Custom Headers",
  "html": "<p>Email content</p>",
  "headers": {
    "X-Custom-Header": "custom-value",
    "X-Priority": "1"
  }
}

Tracking

Enable tracking for opens and clicks:

{
  "to": "user@example.com",
  "subject": "Tracked Email",
  "template": "newsletter",
  "tracking": {
    "opens": true,
    "clicks": true
  }
}

Scheduling

Schedule emails for later delivery:

{
  "to": "user@example.com",
  "subject": "Scheduled Email",
  "template": "reminder",
  "scheduledAt": "2024-12-31T10:00:00Z"
}

Bulk Sending

Send emails in bulk efficiently:

curl -X POST https://your-mailtura-instance.com/api/v1/emails/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Tenant-ID: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "welcome-email",
    "recipients": [
      {
        "to": "user1@example.com",
        "variables": {"firstName": "John"}
      },
      {
        "to": "user2@example.com",
        "variables": {"firstName": "Jane"}
      }
    ]
  }'

Response

Successful email submission returns:

{
  "id": "msg_123456",
  "status": "queued",
  "createdAt": "2024-12-30T10:00:00Z"
}

Error Handling

Handle common errors:

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid email address format"
  }
}

Common error codes:

  • INVALID_RECIPIENT: Invalid email address
  • TEMPLATE_NOT_FOUND: Template doesn’t exist
  • QUOTA_EXCEEDED: Rate limit exceeded
  • INVALID_ATTACHMENT: Attachment too large or invalid

SDK Examples

Node.js

const mailtura = require('@mailtura/client');

const client = mailtura.create({
  apiKey: 'YOUR_API_KEY',
  tenantId: 'acme-corp'
});

await client.emails.send({
  to: 'user@example.com',
  template: 'welcome-email',
  variables: {
    firstName: 'John'
  }
});

Python

from mailtura import Client

client = Client(
    api_key='YOUR_API_KEY',
    tenant_id='acme-corp'
)

client.emails.send(
    to='user@example.com',
    template='welcome-email',
    variables={'firstName': 'John'}
)

Best Practices

  1. Use templates: Maintain consistency and reduce errors
  2. Enable tracking: Monitor email performance
  3. Handle errors: Implement retry logic for failed sends
  4. Validate recipients: Check email format before sending
  5. Respect quotas: Monitor your usage and rate limits
  6. Test thoroughly: Always test templates before production use

Next Steps