Send Transactional Email with SMTP

Use Lumail's SMTP endpoint when an application can only send email through SMTP and cannot call POST /api/v1/emails directly. Common examples include auth providers, billing tools, no-code platforms, and legacy backends.

SMTP messages are treated as transactional by default. They use the same priority delivery lane as the transactional email API, so auth codes, magic links, password resets, and operational emails are not queued behind newsletter or campaign batches.

When to Use SMTP

Use SMTP for:

• authentication codes and magic links
• password resets
• account invitations
• receipts and invoices
• product notifications
• other low-volume operational emails

Do not use the SMTP endpoint for newsletters, broadcasts, or marketing campaigns. Use Lumail campaigns and workflows for bulk sending so unsubscribes, segmentation, scheduling, and campaign reporting stay correct.

Prerequisites

Before configuring SMTP, the organization needs:

1. A verified Lumail email domain.
2. A Lumail API token.
3. An SMTP-capable application that supports STARTTLS on port 587.
4. A From address on the verified domain.

The API token and the verified domain must belong to the same Lumail organization.

Step 1 - Verify a Sending Domain

The From address must use a verified email domain in Lumail.

1. Open your Lumail organization.
2. Go to Settings -> Domains.
3. Add your sending domain, for example yourdomain.com.
4. Add the SPF and DKIM DNS records shown by Lumail.
5. Wait until the domain status is Verified.

If your verified domain is yourdomain.com, valid sender examples include:

[email protected]
[email protected]
[email protected]

Lumail rejects SMTP messages when the From address does not belong to a verified email domain in the same organization as the API token.

Step 2 - Create an API Token

The SMTP password is a Lumail API token, not your Lumail account password.

1. Open your Lumail organization.
2. Go to Settings -> API Tokens.
3. Click Generate Token.
4. Name it clearly, for example Production SMTP.
5. Copy the token immediately and store it in your application's secret manager.

The token starts with lum_.

Step 3 - Configure Your SMTP Client

Use these settings in your external application:

The username is used as a label in SMTP logs. The password is what authenticates the request.

Supabase Auth Example

For Supabase Auth custom SMTP, configure:

Host: smtp.lumail.io
Port: 587
Security: STARTTLS
Username: your-org-slug
Password: lum_your_api_token
Sender email: [email protected]

Use the same sender address in Supabase email templates. The sender domain must already be verified in Lumail.

Nodemailer Example

import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.lumail.io",
  port: 587,
  secure: false,
  requireTLS: true,
  auth: {
    user: "your-org-slug",
    pass: process.env.LUMAIL_API_TOKEN,
  },
});

await transport.sendMail({
  from: "Auth Team <[email protected]>",
  to: "[email protected]",
  subject: "Your login code",
  text: "Your login code is 123456.",
});

Test the Connection

You can test the SMTP endpoint with swaks:

swaks \
  --server smtp.lumail.io \
  --port 587 \
  --tls \
  --auth LOGIN \
  --auth-user your-org-slug \
  --auth-password lum_your_api_token \
  --from [email protected] \
  --to [email protected] \
  --header "Subject: Lumail SMTP test" \
  --body "This email was sent through Lumail SMTP."

A successful response ends with:

250 Queued 1 message(s)

That means Lumail accepted the email and queued it on the transactional priority lane. Final inbox placement still depends on the receiving mailbox and downstream delivery provider.

Message Behavior

Send one SMTP message per recipient. If your application needs bulk sending, use Lumail campaigns or workflows instead.

Troubleshooting

If your provider asks for SSL/TLS on port 465, choose STARTTLS on port 587 instead. Lumail's SMTP endpoint is exposed on 587.

Related Documentation

• SMTP Endpoint Reference - Connection settings and response codes
• Create an API Token - Generate the token used as the SMTP password
• Email Domains - Verify the domain used in your From address
• Send Transactional Email API - Prefer this API when your application supports HTTP