Quick Start

Responsible Use

ThorMail is designed for high-demand professional use: transactional emails, notifications, and legitimate marketing. It is not a spam tool. Users are responsible for complying with anti-spam laws (CAN-SPAM, GDPR, etc.) and adapter terms of service.

This guide will walk you through sending your first message with ThorMail.

Prerequisites

• ThorMail installed and running (Installation Guide)
• Access to the ThorMail dashboard
• A delivery adapter account (SMTP, SendGrid, etc.)
• Valid License Key (Free, get one at thormail.io by verifying your email)

Step 1: Login & Access Workspace

When you start ThorMail for the first time, an admin account and a default workspace are automatically created for you.

1. Get your Admin Password

   The initial password is randomly generated and printed to the container logs. Run:

   docker logs thormail-backend
   # Or with Docker Compose:
   docker compose logs backend

   Look for a line similar to: Admin account created: [email protected] / password: <random_string>

2. Log in to the Dashboard

   • Open http://localhost:3000
   • Log in with your configured EMAIL and the password from the logs.

3. Access your Workspace

   • You will be automatically redirected to your default Workspace.
   • Copy the Workspace ID and API Key from the Developers section in the sidebar.

Caution

Keep your API Key secure! Never expose it in client-side code or public repositories.

Step 2: Configure an Adapter

1. Go to Adapters in the sidebar

2. Manage your Adapters

   • Install: Browse the list and install new adapters (e.g., SendGrid, Mailgun).
   • Configure: Click on an installed adapter to enter your credentials (e.g., API Key, SMTP host).

3. Click Save & Test to verify the configuration

Step 3: Send Your First Message

Use the API to send a message:

cURL

curl -X POST https://your-server:4000/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Workspace-ID: 1" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "to": "[email protected]",
    "subject": "Hello from ThorMail!",
    "body": "<h1>Welcome!</h1><p>This is your first message.</p>"
  }'

JavaScript

const response = await fetch('https://your-server:4000/v1/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Workspace-ID': '1',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    to: '[email protected]',
    subject: 'Hello from ThorMail!',
    body: '<h1>Welcome!</h1><p>This is your first message.</p>'
  })
});

const data = await response.json();
console.log('Message queued with ID:', data.id);

Python

import requests

response = requests.post(
    'https://your-server:4000/v1/send',
    headers={
        'Content-Type': 'application/json',
        'X-Workspace-ID': '1',
        'X-API-Key': 'your-api-key'
    },
    json={
        'to': '[email protected]',
        'subject': 'Hello from ThorMail!',
        'body': '<h1>Welcome!</h1><p>This is your first message.</p>'
    }
)

data = response.json()
print(f"Message queued with ID: {data['id']}")

Response

{
  "id": 12345,
  "status": "accepted"
}

The 202 Accepted response means your message has been queued for delivery. ThorMail will process it asynchronously.

Step 4: Using Template Variables

Personalize your messages with template variables:

curl -X POST https://your-server:4000/v1/send \
  -H "Content-Type: application/json" \
  -H "X-Workspace-ID: 1" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "to": "[email protected]",
    "subject": "Welcome, {{name}}!",
    "body": "<h1>Hello {{name}}!</h1><p>Your order #{{order_id}} has been confirmed.</p>",
    "data": {
      "name": "John",
      "order_id": "ORD-12345"
    }
  }'

ThorMail uses Handlebars-style {{variable}} syntax for template substitution.

Step 5: Monitor Delivery

Check the status of your messages:

1. Go to Queue in the dashboard
2. Find your message by ID or recipient
3. View the delivery status and any error details

Batch Sending

Send to multiple recipients in one request:

curl -X POST https://your-server:4000/v1/send-batch \
  -H "Content-Type: application/json" \
  -H "X-Workspace-ID: 1" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "subject": "Monthly Newsletter",
    "body": "<h1>Hello {{name}}!</h1><p>Here is your monthly update...</p>",
    "emails": [
      { "to": "[email protected]", "data": { "name": "Alice" } },
      { "to": "[email protected]", "data": { "name": "Bob" } },
      { "to": "[email protected]", "data": { "name": "Carol" } }
    ]
  }'

Tip

Batch endpoint supports up to 100 recipients per request and is more efficient than multiple single requests.

What’s Next?

Now that you’ve sent your first message, explore more features:

• API Reference - Complete API documentation
• Multi-Provider Failover - Set up automatic failover
• Templates - Create reusable message templates
• Creating Adapters - Build custom integrations