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 | smtp.arkhq.io |
| Port | 587 (STARTTLS) |
| Username | Your credential (e.g., acme/production) |
| Password | Your credential key |
| Encryption | STARTTLS required |
Alternative Port
| Setting | Value |
|---|---|
| Host | smtp.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).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. |
Popular Applications
Listmonk
Listmonk
Edit your Or via environment variables:
config.toml:Coolify
Coolify
In Settings → Transactional Email:
| Field | Value |
|---|---|
| SMTP Enabled | Yes |
| SMTP Host | smtp.arkhq.io |
| SMTP Port | 587 |
| SMTP Username | your-org/production |
| SMTP Password | your-credential-key |
| Encryption | TLS |
| From Address | noreply@yourdomain.com |
Metabase
Metabase
In Admin → Email:
| Field | Value |
|---|---|
| SMTP Host | smtp.arkhq.io |
| SMTP Port | 587 |
| SMTP Security | TLS |
| SMTP Username | your-org/production |
| SMTP Password | your-credential-key |
| From Address | metabase@yourdomain.com |
Grafana
Grafana
In
grafana.ini or via environment:GitLab
GitLab
In Then run
/etc/gitlab/gitlab.rb:gitlab-ctl reconfigure.WordPress
WordPress
Using WP Mail SMTP plugin:
| Setting | Value |
|---|---|
| Mailer | Other SMTP |
| SMTP Host | smtp.arkhq.io |
| Encryption | TLS |
| SMTP Port | 587 |
| Authentication | On |
| Username | your-org/production |
| Password | your-credential-key |
Ghost
Ghost
In your
config.production.json:n8n
n8n
In Settings → SMTP:
| Field | Value |
|---|---|
| SMTP Host | smtp.arkhq.io |
| SMTP Port | 587 |
| SMTP User | your-org/production |
| SMTP Password | your-credential-key |
| SMTP SSL | false |
| SMTP Sender | n8n@yourdomain.com |
Framework Integration
- Node.js
- Python
- Ruby
- PHP
- Go
Using Nodemailer:
Web Framework Configuration
- Rails
- Django
- Laravel
- Spring Boot
Environment Variables
For most deployments, set these environment variables:Environment variable names vary by application. Check your app’s documentation for the exact names.
Testing Your Connection
Quick Test with swaks
Test TLS Connection
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 |
| Tag | Via X-Ark-Tag header | Native tag parameter |
| Metadata | Via X-Ark-Metadata-* headers | Native metadata object |
| 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
Tag
Use theX-Ark-Tag header to add a tag to your email:
Metadata
Add custom key-value metadata usingX-Ark-Metadata-* headers. Each header becomes a metadata key:
- Maximum 10 metadata keys per email
- Keys: 1-40 characters, must start with a letter, only alphanumeric and underscores
- Values: 1-500 characters, no control characters (newlines, tabs, etc.)
- Total size: 4KB maximum
SMTP is lenient with metadata. Invalid keys are silently skipped rather than rejecting the email. Valid metadata keys are preserved. This differs from the REST API, which returns an error for invalid metadata since you can fix and retry the request.
Billing
SMTP sends are billed the same as REST API sends — included in your plan’s email quota. Your account status is checked when you send each message.SMTP Response Codes
| Code | Meaning |
|---|---|
250 OK | Message accepted |
452 Send limit exceeded | Plan email limit reached — upgrade your plan |
452 Billing not configured | Set up billing in your dashboard |
Example SMTP Session
Fail-open design: If the billing system is temporarily unavailable, SMTP messages are accepted rather than rejected. This ensures your emails aren’t blocked by transient billing issues.
Troubleshooting
452 Send Limit Exceeded
452 Send Limit Exceeded
Cause: Your plan’s email limit has been reached.Solutions:
- Check your usage at arkhq.io/org/billing
- Upgrade to a higher plan for more email volume
- Wait for your next billing cycle to reset the limit
Connection Refused
Connection Refused
Causes:
- Firewall blocking outbound port 587/465
- Cloud provider restricting SMTP (common on AWS, GCP, Azure)
- 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
Authentication Failed
Causes:
- Wrong username format
- Incorrect password
- Suspended credential
- 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
TLS/Certificate Errors
Causes:
- Outdated CA certificates on your system
- Application doesn’t support modern TLS
- Update system CA certificates
- Try port 465 (implicit TLS) instead of 587 (STARTTLS)
- Check your app supports TLS 1.2+
Timeout Errors
Timeout Errors
Causes:
- Network latency
- DNS resolution issues
- SMTP traffic inspection/filtering
- Increase client timeout settings
- Verify DNS resolves
smtp.arkhq.iocorrectly - Check for corporate proxies or firewalls inspecting SMTP
Emails Not Arriving
Emails Not Arriving
Causes:
- Domain not verified
- Recipient on suppression list
- Email marked as spam
- Verify your sending domain in the dashboard
- Check suppressions
- Review email content for spam triggers
- Check recipient’s spam folder
