Configure custom SMTP relay servers and route outbound email through your own infrastructure

SMTP pools let you route outbound email through your own SMTP relay instead of MisarMail's shared sending infrastructure. This is useful when you have an existing arrangement with a provider like Amazon SES, Postfix, Mailgun, or SendGrid, or when you need isolated sending pools for different business units.

The same functionality is available in the dashboard at Settings → SMTP Pools.

Requires active session (dashboard only).

List SMTP pools

GET/api/smtp-pools

Returns all configured SMTP pools for the account. Passwords are never included in responses.

Response fields

[]Array<object>

SMTP pools, each with id, name, host, port, username, encryption, is_active, and created_at.

[
  {
    "id": "smtp_01hx3k",
    "name": "Amazon SES — us-east-1",
    "host": "email-smtp.us-east-1.amazonaws.com",
    "port": 587,
    "username": "AKIAIOSFODNN7EXAMPLE",
    "encryption": "tls",
    "is_active": true,
    "created_at": "2025-05-01T00:00:00Z"
  }
]

Create SMTP pool

POST/api/smtp-pools

Create a new SMTP pool.

Request body

namestringbodyrequired

Display name for the pool.

hoststringbodyrequired

SMTP server hostname.

portintegerbodyrequired

SMTP port.

usernamestringbodyrequired

SMTP authentication username.

passwordstringbodyrequired

SMTP authentication password (stored encrypted).

encryptiontls | ssl | nonebodyrequired

Connection encryption method.

curl -X POST /api/smtp-pools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amazon SES — us-east-1",
    "host": "email-smtp.us-east-1.amazonaws.com",
    "port": 587,
    "username": "AKIAIOSFODNN7EXAMPLE",
    "password": "your-ses-smtp-password",
    "encryption": "tls"
  }'

const res = await fetch('/api/smtp-pools', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Amazon SES — us-east-1',
    host: 'email-smtp.us-east-1.amazonaws.com',
    port: 587,
    username: process.env.SES_USERNAME,
    password: process.env.SES_PASSWORD,
    encryption: 'tls',
  }),
});
const pool = await res.json();

Common provider settings

Provider	Host	Port	Encryption
Amazon SES	`email-smtp.<region>.amazonaws.com`	`587`	`tls`
Mailgun	`smtp.mailgun.org`	`587`	`tls`
SendGrid	`smtp.sendgrid.net`	`587`	`tls`
Postfix (self-hosted)	Your server IP/hostname	`587`	`tls`
Gmail SMTP	`smtp.gmail.com`	`465`	`ssl`

Test SMTP connection

POST/api/smtp-pools/:id/test

Sends a test connection to the configured SMTP server. No request body is required.

Path parameters

idstringpathrequired

ID of the SMTP pool to test.

Response fields

successboolean

true when the connection succeeded.

messagestring

Human-readable result message.

latencyMsnumber

Connection latency in milliseconds.

errorstring

Error detail, present only on failure.

{
  "success": true,
  "message": "SMTP connection successful",
  "latencyMs": 142
}

{
  "success": false,
  "message": "SMTP connection failed",
  "latencyMs": 5000,
  "error": "connect ECONNREFUSED 198.51.100.1:587"
}

The test sends an SMTP EHLO and authenticates — it does not send an actual email. A successful test confirms the credentials and port are correct.

Using an SMTP pool for sends

Once a pool is created, reference it by including alias_id in your send request:

curl -X POST https://api.misar.io/mail/v1/send \
  -H "Authorization: Bearer msk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "[email protected]" }],
    "from": { "email": "[email protected]", "name": "Acme" },
    "subject": "Your order is confirmed",
    "html": "<p>Thanks for your order!</p>",
    "alias_id": "smtp_01hx3k"
  }'

If alias_id is omitted, MisarMail uses its default shared sending pool.

Amazon SES setup notes

Verify your sending domain in the SES console
Request production access if you are out of the SES sandbox
Create SMTP credentials in SES → Account dashboard → SMTP settings → Create SMTP credentials
Use port 587 with STARTTLS (tls encryption)
Ensure your EC2 or VPS security group allows outbound TCP on port 587

Amazon SES SMTP credentials (access key + secret) are different from your AWS IAM credentials. Generate them specifically in the SES console.