Koltrix logoKoltrixDocs
Send

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

SettingValue
Hostsmtp.koltrix.com
Port2525
EncryptionSTARTTLS (TLS 1.2 or later, certificate for smtp.koltrix.com). Connect, send EHLO, upgrade with STARTTLS, then authenticate. Most libraries do this automatically.
AuthenticationAUTH PLAIN or AUTH LOGIN
Usernameapikey (any value is accepted)
PasswordAn API key with the send scope
Message size25 MB per message
Recipients1,000 per message
Connection timeA connection is closed after 5 minutes
Connections300 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 sessionUsed 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 TOA 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: headerThe subject. Encoded words (=?UTF-8?B?…?=) are decoded.
A text/plain or text/html body, or a multipart/alternative with one of eachThe 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)

Node.js
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)

Python
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:

Go
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
<?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 Bye

The 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

CodeWhenWhat to do
235 2.7.0Authentication succeeded.
250Command accepted, or 250 2.0.0 OK: queued after DATA.
451 4.3.0 Queue failure, try againKoltrix couldn't queue the message.Retry later; your client normally does.
452 4.5.3 Too many recipientsMore 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.1The 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 addressThe address couldn't be read.Wrap it in angle brackets: MAIL FROM:<[email protected]>.
501 5.5.2 Cannot decode credentialsThe AUTH PLAIN argument isn't valid base64.
500 5.5.2 Line too longA command line over 4,096 bytes. The connection is closed.
502 5.5.2Unknown command.
503 5.5.1Commands out of order (RCPT before MAIL, DATA before RCPT), or AUTH after the session already authenticated.
504 5.5.4An authentication method other than PLAIN or LOGIN.
530 5.7.0 Authentication requiredMAIL 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 failuresFive failed AUTHs on one connection. The connection is closed.Check the key.
421 4.3.2 Too many connectionsThe 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 failureKoltrix 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 limitThe message is over 25 MB.Permanent; retrying the same message won't help.
554 5.6.0 Data read errorThe 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 send scope. Authentication fails with 535 … key missing 'send' permission. Create a key with send.