SMTP Integration

While the REST API is recommended for modern applications, Ark supports standard SMTP for tools and frameworks that require it. Change one configuration and start sending through Ark instantly.

When to use SMTP: Self-hosted applications (Listmonk, Coolify, Metabase), legacy systems, or any software with built-in SMTP support but no HTTP API options.

Connection Details

Quick Reference

Setting	Value
Host	`mail.arkhq.io`
Port	`587` (STARTTLS)
Username	Your credential (e.g., `acme/production`)
Password	Your credential key
Encryption	STARTTLS required

Alternative Port

Setting	Value
Host	`mail.arkhq.io`
Port	`465` (Implicit TLS)
Username	Your credential (e.g., `acme/production`)
Password	Your credential key
Encryption	TLS from start

Get Your Credentials

Open the Credentials Page

Go to arkhq.io/org/credentials in your dashboard.

Create or Select a Credential

Each credential has a username (like acme/production) and a key (your password).

Copy the Values

Use the username as your SMTP username and the key as your SMTP password.

Never share your credential key. It provides full sending access to your account. Rotate keys immediately if compromised.

Port Selection

Port	Encryption	Best For
587	STARTTLS	Most applications. Connection upgrades to TLS after EHLO.
465	Implicit TLS	Older apps that don’t support STARTTLS. Encrypted from the start.

Which should I use? Start with port 587. Only use 465 if your application doesn’t support STARTTLS or you encounter connection issues.

Popular Applications

Listmonk

Edit your config.toml:

[smtp]
host = "mail.arkhq.io"
port = 587
auth_protocol = "login"
username = "your-org/production"
password = "your-credential-key"
tls_type = "STARTTLS"
max_conns = 10

Or via environment variables:

LISTMONK_smtp__host=mail.arkhq.io
LISTMONK_smtp__port=587
LISTMONK_smtp__auth_protocol=login
LISTMONK_smtp__username=your-org/production
LISTMONK_smtp__password=your-credential-key
LISTMONK_smtp__tls_type=STARTTLS

Coolify

In Settings → Transactional Email:

Field	Value
SMTP Enabled	Yes
SMTP Host	`mail.arkhq.io`
SMTP Port	`587`
SMTP Username	`your-org/production`
SMTP Password	`your-credential-key`
Encryption	`TLS`
From Address	`[email protected]`

Metabase

In Admin → Email:

Field	Value
SMTP Host	`mail.arkhq.io`
SMTP Port	`587`
SMTP Security	`TLS`
SMTP Username	`your-org/production`
SMTP Password	`your-credential-key`
From Address	`[email protected]`

Grafana

In grafana.ini or via environment:

[smtp]
enabled = true
host = mail.arkhq.io:587
user = your-org/production
password = your-credential-key
from_address = [email protected]
starttls_policy = MandatoryStartTLS

GitLab

In /etc/gitlab/gitlab.rb:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "mail.arkhq.io"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "your-org/production"
gitlab_rails['smtp_password'] = "your-credential-key"
gitlab_rails['smtp_domain'] = "yourdomain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

Then run gitlab-ctl reconfigure.

WordPress

Using WP Mail SMTP plugin:

Setting	Value
Mailer	`Other SMTP`
SMTP Host	`mail.arkhq.io`
Encryption	`TLS`
SMTP Port	`587`
Authentication	`On`
Username	`your-org/production`
Password	`your-credential-key`

Ghost

In your config.production.json:

{
  "mail": {
    "transport": "SMTP",
    "options": {
      "host": "mail.arkhq.io",
      "port": 587,
      "secure": false,
      "auth": {
        "user": "your-org/production",
        "pass": "your-credential-key"
      }
    }
  }
}

n8n

In Settings → SMTP:

Field	Value
SMTP Host	`mail.arkhq.io`
SMTP Port	`587`
SMTP User	`your-org/production`
SMTP Password	`your-credential-key`
SMTP SSL	`false`
SMTP Sender	`[email protected]`

Framework Integration

Node.js
Python
Ruby
PHP
Go

Using Nodemailer:

import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransport({
  host: 'mail.arkhq.io',
  port: 587,
  secure: false, // true for 465, false for 587
  auth: {
    user: process.env.SMTP_USERNAME,
    pass: process.env.SMTP_PASSWORD,
  },
});

await transporter.sendMail({
  from: '"Your App" <[email protected]>',
  to: '[email protected]',
  subject: 'Welcome!',
  text: 'Thanks for signing up.',
  html: '<p>Thanks for signing up.</p>',
});

Using smtplib:

import smtplib
import os
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

msg = MIMEMultipart("alternative")
msg["Subject"] = "Welcome!"
msg["From"] = "Your App <[email protected]>"
msg["To"] = "[email protected]"

msg.attach(MIMEText("Thanks for signing up.", "plain"))
msg.attach(MIMEText("<p>Thanks for signing up.</p>", "html"))

with smtplib.SMTP("mail.arkhq.io", 587) as server:
    server.starttls()
    server.login(
        os.environ["SMTP_USERNAME"],
        os.environ["SMTP_PASSWORD"]
    )
    server.sendmail(msg["From"], msg["To"], msg.as_string())

Using the Mail gem:

require "mail"

Mail.defaults do
  delivery_method :smtp, {
    address: "mail.arkhq.io",
    port: 587,
    user_name: ENV["SMTP_USERNAME"],
    password: ENV["SMTP_PASSWORD"],
    authentication: :plain,
    enable_starttls_auto: true
  }
end

Mail.deliver do
  from    "Your App <[email protected]>"
  to      "[email protected]"
  subject "Welcome!"
  body    "Thanks for signing up."
end

Using PHPMailer:

<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;

$mail = new PHPMailer(true);

$mail->isSMTP();
$mail->Host       = 'mail.arkhq.io';
$mail->SMTPAuth   = true;
$mail->Username   = getenv('SMTP_USERNAME');
$mail->Password   = getenv('SMTP_PASSWORD');
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port       = 587;

$mail->setFrom('[email protected]', 'Your App');
$mail->addAddress('[email protected]');
$mail->Subject = 'Welcome!';
$mail->Body    = '<p>Thanks for signing up.</p>';
$mail->AltBody = 'Thanks for signing up.';

$mail->send();

Using net/smtp:

package main

import (
    "net/smtp"
    "os"
)

func main() {
    auth := smtp.PlainAuth(
        "",
        os.Getenv("SMTP_USERNAME"),
        os.Getenv("SMTP_PASSWORD"),
        "mail.arkhq.io",
    )

    msg := []byte("To: [email protected]\r\n" +
        "Subject: Welcome!\r\n" +
        "Content-Type: text/plain; charset=utf-8\r\n" +
        "\r\n" +
        "Thanks for signing up.\r\n")

    smtp.SendMail(
        "mail.arkhq.io:587",
        auth,
        "[email protected]",
        []string{"[email protected]"},
        msg,
    )
}

Web Framework Configuration

Rails
Django
Laravel
Spring Boot

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "mail.arkhq.io",
  port: 587,
  user_name: ENV["SMTP_USERNAME"],
  password: ENV["SMTP_PASSWORD"],
  authentication: :plain,
  enable_starttls_auto: true
}

# settings.py
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "mail.arkhq.io"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = os.environ.get("SMTP_USERNAME")
EMAIL_HOST_PASSWORD = os.environ.get("SMTP_PASSWORD")
DEFAULT_FROM_EMAIL = "Your App <[email protected]>"

// .env
MAIL_MAILER=smtp
MAIL_HOST=mail.arkhq.io
MAIL_PORT=587
MAIL_USERNAME="${SMTP_USERNAME}"
MAIL_PASSWORD="${SMTP_PASSWORD}"
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

# application.yml
spring:
  mail:
    host: mail.arkhq.io
    port: 587
    username: ${SMTP_USERNAME}
    password: ${SMTP_PASSWORD}
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true

Environment Variables

For most deployments, set these environment variables:

SMTP_HOST=mail.arkhq.io
SMTP_PORT=587
SMTP_USERNAME=your-org/production
SMTP_PASSWORD=your-credential-key
SMTP_FROM=[email protected]

Environment variable names vary by application. Check your app’s documentation for the exact names.

Testing Your Connection

Quick Test with swaks

swaks --to [email protected] \
  --from [email protected] \
  --server mail.arkhq.io:587 \
  --auth LOGIN \
  --auth-user "your-org/production" \
  --auth-password "your-credential-key" \
  --tls \
  --header "Subject: SMTP Test" \
  --body "If you see this, SMTP is working!"

Test TLS Connection

openssl s_client -connect mail.arkhq.io:587 -starttls smtp

You should see certificate information and 250 responses from the server.

Success! If you receive the test email, your SMTP configuration is working correctly.

SMTP vs REST API

Feature	SMTP	REST API
Best for	Self-hosted apps, legacy systems	Modern applications
Setup	Configuration change	SDK or HTTP client
Tracking	Automatic via Ark	Explicit parameters
Batch sending	Sequential	Up to 100 per request
Metadata/Tags	Via headers (X-Postal-Tag)	Native parameters
Attachments	Standard MIME	Base64 in JSON

Same features, different interface. Emails sent via SMTP appear in the same dashboard, trigger the same webhooks, and use the same tracking as REST API emails. The only difference is how you send them.

Adding Tags and Metadata via SMTP

Use custom headers to add tags to your SMTP emails:

X-Postal-Tag: welcome-email

These tags appear in your dashboard and webhook events, just like REST API tags.

Troubleshooting

Connection Refused

Causes:

Firewall blocking outbound port 587/465
Cloud provider restricting SMTP (common on AWS, GCP, Azure)

Solutions:

Check firewall rules allow outbound 587/465
For AWS: Request SMTP sending limits removal
For GCP: Use port 587, not 25
Try port 465 if 587 is blocked

Authentication Failed

Causes:

Wrong username format
Incorrect password
Suspended credential

Solutions:

Username format is org-name/credential-name (check dashboard)
Use the credential key, not the credential ID
Verify credential is active in dashboard

TLS/Certificate Errors

Causes:

Outdated CA certificates on your system
Application doesn’t support modern TLS

Solutions:

Update system CA certificates
Try port 465 (implicit TLS) instead of 587 (STARTTLS)
Check your app supports TLS 1.2+

Timeout Errors

Causes:

Network latency
DNS resolution issues
SMTP traffic inspection/filtering

Solutions:

Increase client timeout settings
Verify DNS resolves mail.arkhq.io correctly
Check for corporate proxies or firewalls inspecting SMTP

Emails Not Arriving

Causes:

Domain not verified
Recipient on suppression list
Email marked as spam

Solutions:

Verify your sending domain in the dashboard
Check suppressions
Review email content for spam triggers
Check recipient’s spam folder

Next Steps

Set Up Your Domain

Configure DNS for better deliverability

Track Delivery

Get notified when emails are delivered or bounce

REST API Alternative

More control with the REST API

Email Lifecycle

Understand delivery statuses and retries

Getting Started

Guides

Concepts

Reference

Connection Details

Quick Reference

Alternative Port

Get Your Credentials

Port Selection

Popular Applications

Framework Integration

Web Framework Configuration

Environment Variables

Testing Your Connection

Quick Test with swaks

Test TLS Connection

SMTP vs REST API

Adding Tags and Metadata via SMTP

Troubleshooting

Next Steps

Set Up Your Domain

Track Delivery

REST API Alternative

Email Lifecycle

Getting Started

Guides

Concepts

Reference

​Connection Details

Quick Reference

Alternative Port

​Get Your Credentials

​Port Selection

​Popular Applications

​Framework Integration

​Web Framework Configuration

​Environment Variables

​Testing Your Connection

​Quick Test with swaks

​Test TLS Connection

​SMTP vs REST API

​Adding Tags and Metadata via SMTP

​Troubleshooting

​Next Steps

Set Up Your Domain

Track Delivery

REST API Alternative

Email Lifecycle

Connection Details

Get Your Credentials

Port Selection

Popular Applications

Framework Integration

Web Framework Configuration

Environment Variables

Testing Your Connection

Quick Test with swaks

Test TLS Connection

SMTP vs REST API

Adding Tags and Metadata via SMTP

Troubleshooting

Next Steps