Via API

Send emails programmatically through the REST API

Send emails programmatically through Mailtura’s REST API for integration with your applications.

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