SMTP relay
Point software that already speaks SMTP at Koltrix and authenticate with an API key. Messages accepted by the relay go through the same pipeline as the REST API: the same suppression list, signing, message log, send quota and webhooks.
If you are writing new code, use the REST API instead. It returns the message id, supports idempotent retries and tells you in JSON what went wrong.
Connection settings
| Setting | Value |
|---|---|
| Host | smtp.koltrix.com |
| Port | 2525 |
| Encryption | STARTTLS (TLS 1.2 or later, certificate for smtp.koltrix.com). Connect, send EHLO, upgrade with STARTTLS, then authenticate. Most libraries do this automatically. |
| Authentication | AUTH PLAIN or AUTH LOGIN |
| Username | apikey (any value is accepted) |
| Password | An API key with the send scope |
| Message size | 25 MB per message |
| Recipients | 1,000 per message |
| Connection time | A connection is closed after 5 minutes |
| Connections | 300 at once, and 50 from one address |
Ports 587 and 465 are not the relay and don't accept API keys.
What the relay reads from your message
The relay is built for transactional mail with a simple body. It takes:
| From your SMTP session | Used as |
|---|---|
MAIL FROM (the envelope sender) | The From address of the sent message. It must be an active address on a verified domain in your workspace, exactly as for the REST API; anything else is refused with 553 5.7.1 Sender not authorized. |
Each RCPT TO | A recipient. Recipients named in your message's To: or Cc: header appear there; any other RCPT TO is delivered as a Bcc and never shown in the headers. |
The Subject: header | The subject. Encoded words (=?UTF-8?B?…?=) are decoded. |
A text/plain or text/html body, or a multipart/alternative with one of each | The message body. Quoted-printable and base64 bodies and other charsets (UTF-8, ISO-8859-1, Windows-1252…) are decoded. An HTML-only message also gets a plain-text version generated from it. |
The To: and Cc: headers only decide how each RCPT TO recipient is shown.
Everything else in the message is ignored: the From:, Bcc: and Reply-To:
headers, display names and any custom headers. Put every recipient in
RCPT TO. The same address named twice is one recipient.
Examples
swaks
The quickest way to check that a key works:
swaks --server smtp.koltrix.com --port 2525 --tls \
--auth PLAIN --auth-user apikey --auth-password "$KOLTRIX_API_KEY" \
--from [email protected] --to [email protected] \
--header "Subject: Hello via SMTP" \
--body "It works."The last reply should be 250 2.0.0 OK: queued.
Node.js (nodemailer)
import nodemailer from "nodemailer";
const transport = nodemailer.createTransport({
host: "smtp.koltrix.com",
port: 2525,
secure: false,
auth: { user: "apikey", pass: process.env.KOLTRIX_API_KEY },
});
await transport.sendMail({
from: "[email protected]",
to: "[email protected]",
subject: "Hello via SMTP",
html: "<p>It works.</p>", // one body only: html or text, not both
});Python (smtplib)
import os
import smtplib
from email.message import EmailMessage
msg = EmailMessage()
msg["From"] = "[email protected]"
msg["To"] = "[email protected]"
msg["Subject"] = "Hello via SMTP"
msg.set_content("<p>It works.</p>", subtype="html") # a single HTML part
with smtplib.SMTP("smtp.koltrix.com", 2525) as s:
s.starttls()
s.login("apikey", os.environ["KOLTRIX_API_KEY"])
s.send_message(msg)Go (net/smtp)
smtp.SendMail upgrades to STARTTLS on its own, and smtp.PlainAuth then
sends the key inside the encrypted connection:
package main
import (
"net/smtp"
"os"
)
func main() {
msg := []byte("From: [email protected]\r\n" +
"To: [email protected]\r\n" +
"Subject: Hello via SMTP\r\n" +
"Content-Type: text/html; charset=UTF-8\r\n" +
"\r\n" +
"<p>It works.</p>\r\n")
auth := smtp.PlainAuth("", "apikey", os.Getenv("KOLTRIX_API_KEY"), "smtp.koltrix.com")
err := smtp.SendMail("smtp.koltrix.com:2525", auth,
"[email protected]", []string{"[email protected]"}, msg)
if err != nil {
panic(err)
}
}PHP (PHPMailer)
<?php
use PHPMailer\PHPMailer\PHPMailer;
$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = "smtp.koltrix.com";
$mail->Port = 2525;
$mail->SMTPAuth = true;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Username = "apikey";
$mail->Password = getenv("KOLTRIX_API_KEY");
$mail->setFrom("[email protected]");
$mail->addAddress("[email protected]");
$mail->Subject = "Hello via SMTP";
$mail->isHTML(true);
$mail->Body = "<p>It works.</p>"; // leave AltBody empty: one part only
$mail->send();A session, line by line
S: 220 koltrix-smtp ready
C: EHLO app.acme.com
S: 250-koltrix-smtp
S: 250-STARTTLS
S: 250-8BITMIME
S: 250-SIZE 26214400
S: 250 HELP
C: STARTTLS
S: 220 2.0.0 Ready to start TLS
(TLS handshake; everything below is encrypted)
C: EHLO app.acme.com
S: 250-koltrix-smtp
S: 250-AUTH PLAIN LOGIN
S: 250-8BITMIME
S: 250-SIZE 26214400
S: 250 HELP
C: AUTH PLAIN AGFwaWtleQBreF8uLi4=
S: 235 2.7.0 Authentication successful
C: MAIL FROM:<[email protected]>
S: 250 2.1.0 OK
C: RCPT TO:<[email protected]>
S: 250 2.1.5 OK
C: DATA
S: 354 End data with <CR><LF>.<CR><LF>
C: Subject: Hello via SMTP
C: Content-Type: text/plain; charset=UTF-8
C:
C: It works.
C: .
S: 250 2.0.0 OK: queued
C: QUIT
S: 221 2.0.0 ByeThe AUTH PLAIN argument is the base64 of a null byte, the username, a null
byte and the API key. The relay understands EHLO, HELO, AUTH, STARTTLS,
MAIL, RCPT, DATA, RSET, NOOP and QUIT. A session authenticates
once; a second AUTH is refused.
Until the relay stops accepting AUTH on an unencrypted connection (see the
warning above), the first EHLO reply also lists 250-AUTH PLAIN LOGIN.
Ignore it and upgrade first, as the session above does.
Reply codes
| Code | When | What to do |
|---|---|---|
235 2.7.0 | Authentication succeeded. | |
250 | Command accepted, or 250 2.0.0 OK: queued after DATA. | |
451 4.3.0 Queue failure, try again | Koltrix couldn't queue the message. | Retry later; your client normally does. |
452 4.5.3 Too many recipients | More than 1,000 RCPT TO in one message. | Send the rest in another message. |
452 4.5.3 …sending limit… | Your plan's send quota is used up (at RCPT or DATA). | Temporary on purpose: your client keeps retrying while you upgrade or the quota resets. See Limits. |
553 5.7.1 | The MAIL FROM address is not an active address on a verified domain in your workspace. | Send from one of your workspace's addresses (Settings → Domains). |
501 5.5.4 Invalid FROM address / Invalid TO address | The address couldn't be read. | Wrap it in angle brackets: MAIL FROM:<[email protected]>. |
501 5.5.2 Cannot decode credentials | The AUTH PLAIN argument isn't valid base64. | |
500 5.5.2 Line too long | A command line over 4,096 bytes. The connection is closed. | |
502 5.5.2 | Unknown command. | |
503 5.5.1 | Commands out of order (RCPT before MAIL, DATA before RCPT), or AUTH after the session already authenticated. | |
504 5.5.4 | An authentication method other than PLAIN or LOGIN. | |
530 5.7.0 Authentication required | MAIL FROM before AUTH. | |
535 5.7.8 Authentication failed (…) | The password isn't a kx_ key, the key is invalid or revoked, it lacks the send scope, or its workspace is suspended. The text in brackets says which. | |
421 4.7.0 Too many authentication failures | Five failed AUTHs on one connection. The connection is closed. | Check the key. |
421 4.3.2 Too many connections | The relay has too many open connections (300 overall, 50 from one address). | Retry shortly; close idle connections. |
450 4.7.0 … (a sentence such as "Your trial has ended. Your mail is safe…") | The workspace is read-only: the trial ended, a payment failed past its grace period, or the subscription ended. Temporary on purpose: your mail server queues the message and retries, so a plan activated in time loses nothing. | Choose or fix a plan in Settings → Billing. |
454 4.7.0 Temporary authentication failure | Koltrix couldn't look the key up. It says nothing about the key. | Retry. |
554 5.6.0 Message not accepted: … | The message has a part the relay can't carry (attachment, image, calendar) or can't be parsed. The text says which. | Send a text or HTML body only. Permanent. |
552 5.3.4 Message size exceeds fixed limit | The message is over 25 MB. | Permanent; retrying the same message won't help. |
554 5.6.0 Data read error | The connection broke during DATA. |
Common mistakes
- Using port 587 or 465. Those ports don't accept API keys. Use
2525. - Switching TLS off. Use
STARTTLS(the libraries' "TLS" or "STARTTLS" setting; not "SSL/TLS on connect", which is port 465 style and not offered here). - Expecting the
From:header to be used. The relay sends from the envelope sender. Most libraries set both to the same address; check yours does. - Attachments or inline images. The relay refuses them; see the limitation above. Text and HTML together are fine.
- A key without the
sendscope. Authentication fails with535 … key missing 'send' permission. Create a key withsend.