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: ```text auth@yourdomain.com support@yourdomain.com noreply@yourdomain.com ``` 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: | Setting | Value | | -------- | ------------------------------------------ | | Host | `smtp.lumail.io` | | Port | `587` | | Security | STARTTLS | | Username | Your organization slug, or any label | | Password | Your Lumail API token | | From | An address on a verified Lumail domain | | To | The recipient address for the notification | 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: ```text Host: smtp.lumail.io Port: 587 Security: STARTTLS Username: your-org-slug Password: lum_your_api_token Sender email: auth@your-verified-domain.com ``` Use the same sender address in Supabase email templates. The sender domain must already be verified in Lumail. ## Nodemailer Example ```javascript 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 ", to: "user@example.com", subject: "Your login code", text: "Your login code is 123456.", }); ``` ## Test the Connection You can test the SMTP endpoint with `swaks`: ```bash swaks \ --server smtp.lumail.io \ --port 587 \ --tls \ --auth LOGIN \ --auth-user your-org-slug \ --auth-password lum_your_api_token \ --from auth@your-verified-domain.com \ --to user@example.com \ --header "Subject: Lumail SMTP test" \ --body "This email was sent through Lumail SMTP." ``` A successful response ends with: ```text 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 | Behavior | Default | | -------------- | ------------------------------------------------------------------ | | Delivery lane | Transactional priority | | Recipients | 1 recipient per SMTP message | | Attachments | Rejected | | Size limit | 1 MB | | Link tracking | Disabled | | Open tracking | Disabled | | Content format | HTML is preserved when present; otherwise text is sent as Markdown | Send one SMTP message per recipient. If your application needs bulk sending, use Lumail campaigns or workflows instead. ## Troubleshooting | SMTP response | Meaning | Fix | | ------------- | ---------------------------------------- | ----------------------------------------------------------- | | `535` | Invalid API token | Check the token starts with `lum_` and has not been deleted | | `530` | Authentication required | Enable SMTP AUTH in your application | | `550` | Invalid sender, recipient, or message | Verify the `From` domain and message content | | `552` | Message too large or attachment rejected | Keep the message under 1 MB and remove attachments | | `452` | Temporary quota, rate, or plan issue | Retry later or check organization limits | | `451` | Lumail API temporarily unavailable | Retry with exponential backoff | 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](/docs/api-reference/smtp) - Connection settings and response codes - [Create an API Token](/docs/tutorials/create-api-token) - Generate the token used as the SMTP password - [Email Domains](/docs/domains/email-domains) - Verify the domain used in your `From` address - [Send Transactional Email API](/docs/api-reference/api-emails-send) - Prefer this API when your application supports HTTP