Solving 421 Maximum message count per session reached errors

[MaximilianKohler]

I'm attempting to solve the 421 Connection closed by server. Maximum message count per session reached. errors. Discussed in this thread: knadh/listmonk#1717

I submitted a PR for a retry delay: knadh/listmonk#2309

Chat GPT says it won't fix the issue, and it may be right.

I suggested adding "Max messages per SMTP connection": knadh/listmonk#2683

GPT says the correct fix is not to knadh/listmonk but rather to knadh/smtppool.

What would actually fix SES 421 cleanly

One of these must happen:

✅ Option A (best, architectural)

Add per-connection message limits to smtppool

Close and replace the connection before SES does

This is what we discussed earlier (MaxMessagesPerConn)

This belongs in smtppool, not listmonk

Next step (when you’re ready)

When you follow up about smtppool, I can:

Draft the exact PR for knadh/smtppool

Include SES-specific 421 handling

Add MaxMessagesPerConn cleanly

Make it upstream-acceptable

Should I continue with that? I'm unsure if SES-specific 421 handling is desirable.

EDIT: I asked GPT about the SES-specific part and it said:

That’s a very good instinct, and you’re right to be cautious. Let me clarify what “SES-specific” means here — and how to do this without hard-coding SES behavior or breaking generic SMTP correctness.

You should not add “if SES then …” logic anywhere.

The correct fix is SMTP-generic:

If the server closes the connection or returns a 421 during DATA / send, the client must discard that connection and retry on a fresh one.

That behavior happens to fix SES — but it is valid SMTP behavior for any server.

The full GPT response

That’s a very good instinct, and you’re right to be cautious. Let me clarify what “SES-specific” means here — and how to do this without hard-coding SES behavior or breaking generic SMTP correctness.

---

Short answer (TL;DR)

You should not add “if SES then …” logic anywhere.

The correct fix is SMTP-generic:

If the server closes the connection or returns a 421 during DATA / send, the client must discard that connection and retry on a fresh one.

That behavior happens to fix SES — but it is valid SMTP behavior for any server.

---

Why SES triggers this more often

Amazon SES enforces:

• a maximum number of messages per SMTP session

• once exceeded, it responds with:

  421 Connection closed by server. Maximum message count per session reached.
  

• and closes the TCP connection

SES is just being explicit about it.

Other SMTP servers may:

• silently drop the connection
• respond with 421, 451, or just EOF
• enforce limits based on time, message count, or size

SES is not unique — it’s just well-documented and predictable.

---

What SMTP RFCs say (why this is generic)

From RFC 5321 (SMTP):

• 421 = Service not available, closing transmission channel

• Client behavior:

  • The connection is no longer usable
  • The client must reconnect to continue sending mail
  • Retrying on the same connection is invalid

So a correct SMTP client must:

1. Treat 421 as a connection-terminal error
2. Close and discard that connection
3. Retry the message on a new connection (subject to retry policy)

That is not SES-specific — that is SMTP-correct.

---

What not to do (this would be SES-specific and wrong)

❌ Matching the literal error string:

if strings.Contains(err.Error(), "Maximum message count per session") {
    // SES hack
}

❌ Hard-coding message limits like “1000 per connection” in listmonk

❌ Detecting SES by hostname and branching behavior

Those would indeed be inappropriate.

---

What is appropriate (generic, correct, upstreamable)

1. Treat 421 as a dead connection

In smtppool, when a send returns an error that is:

• SMTP code 421
• or EOF / broken pipe during DATA
• or “connection closed” mid-send

then the pool must:

• close and discard that connection
• not return it to the pool
• optionally retry the message once on a new connection

This logic applies to all SMTP servers.

---

2. Optional (but ideal): connection lifetime limits

Separately from error handling, adding:

MaxMessagesPerConn

is also SMTP-agnostic:

• Many MTAs enforce:

  • max messages per session
  • max time per session

• Limiting connection lifetime proactively is standard practice

• Postfix, Exim, and Sendmail all do this

This is preventive, not SES-specific.

---

Why listmonk alone can’t fix this correctly

listmonk:

• Calls pool.Send(em)

• Does not control:

  • which connection is used
  • whether it’s dead or alive
  • when it’s reused

So:

• retry logic in listmonk cannot guarantee a new connection
• only the pool can do that correctly

That’s why the fix belongs in smtppool.

---

How to describe this in a PR (important wording)

If/when you open a PR to knadh/smtppool, I strongly recommend language like:

This change improves SMTP correctness by discarding and recreating pooled connections when the server closes the session (e.g. on SMTP 421 responses or unexpected EOF). This behavior is SMTP-generic and required by RFC 5321. It also prevents issues with MTAs that enforce per-session message limits.

Notice:

• No mention of SES
• No provider-specific wording
• Pure protocol correctness

---

Mental model (why this is the right abstraction)

Think of it like HTTP keep-alive:

• If the server closes the socket
• the client must not reuse it
• and must retry the request on a new connection

SMTP pooling is the same.

SES just happens to be a very visible case where incorrect reuse causes failures.

---

Bottom line

You’re absolutely right:

• listmonk should remain SMTP-agnostic
• SES should not be special-cased

The correct fix:

• Is protocol-correct
• Belongs in smtppool
• Benefits all SMTP providers
• Happens to fix SES 421 as a consequence

When you’re ready, I can help you:

• phrase the smtppool PR correctly
• implement the logic in a generic way
• anticipate maintainer objections and address them cleanly

You’re thinking about this exactly the right way.

So I'll go ahead with the PR.

[MaximilianKohler]

GPT says:

I’ll walk you through a clean, SMTP-generic smtppool PR that:

• does not special-case SES
• improves RFC-correct behavior
• will likely be acceptable upstream
• permanently resolves the 421/session-limit class of errors

I’ll break this into design, exact code changes, and PR positioning.

---

1. What the smtppool PR should do (scope)

Your PR should do two things only:

A. Treat certain send errors as connection-terminal

When an SMTP send fails due to:

• 421 responses
• unexpected EOF
• broken pipe / connection reset

👉 that connection must never be returned to the pool.

B. Retry the message once on a fresh connection

If a connection dies during send:

• discard it
• open a new one
• retry the message once (not infinitely)

This matches how Postfix, Exim, and other MTAs behave.

No provider detection.
No message-count logic yet (that can be a follow-up PR if desired).

---

2. Where to change code in knadh/smtppool

Relevant files (current repo layout)

You’ll likely touch:

• pool.go
• conn.go (or equivalent; names may vary slightly)

Look for:

• the method that sends an email (often Send or send)
• the struct representing a pooled SMTP connection

---

3. Step-by-step code changes

Step 1: Identify terminal SMTP errors

Add a helper function (generic, RFC-based):

func isTerminalSMTPError(err error) bool {
	if err == nil {
		return false
	}

	s := strings.ToLower(err.Error())

	// RFC 5321: 421 = service not available, closing transmission channel
	if strings.Contains(s, "421") {
		return true
	}

	// Network / connection-level failures
	if strings.Contains(s, "connection reset") ||
		strings.Contains(s, "broken pipe") ||
		strings.Contains(s, "use of closed network connection") ||
		strings.Contains(s, "unexpected eof") ||
		strings.Contains(s, "eof") {
		return true
	}

	return false
}

This is not SES-specific:

• 421 is SMTP-defined
• EOF / reset are transport-level

---

Step 2: Ensure dead connections are discarded

In the code that sends mail using a pooled connection, you’ll see something like:

conn := p.get()
err := conn.send(email)
p.put(conn)
return err

Change the logic to:

conn := p.get()
err := conn.send(email)

if err != nil {
	if isTerminalSMTPError(err) {
		// Do NOT return this connection to the pool
		conn.close()
		p.discard(conn)

		// Retry once on a fresh connection
		conn2 := p.get()
		err2 := conn2.send(email)
		if err2 != nil {
			conn2.close()
			p.discard(conn2)
			return err2
		}

		p.put(conn2)
		return nil
	}

	// Non-terminal error: safe to reuse
	p.put(conn)
	return err
}

p.put(conn)
return nil

Important notes:

• Terminal error = never reused
• Retry only once
• Pool integrity preserved

---

Step 3: Make sure discard() really discards

If the pool does not yet have a discard() method, add one:

func (p *Pool) discard(c *conn) {
	// decrement active count, do not requeue
	p.mu.Lock()
	defer p.mu.Unlock()
	p.active--
}

And ensure close() shuts down the SMTP client cleanly.

---

4. What you should NOT include (for first PR)

Do not include:

• message counters
• per-connection message limits
• SES wording
• config options

This keeps the PR:

• minimal
• obviously correct
• hard to reject

You can add MaxMessagesPerConn in a second PR once this lands.

---

5. How to title the PR

Good titles:

Discard pooled SMTP connections on terminal send errors (RFC-compliant)

or

Fix SMTP connection reuse after server-closed sessions

Avoid:

• “Fix SES”
• “Amazon”
• “message count limit”

---

6. How to explain it in the PR description

Here is text you can almost copy-paste:

Some SMTP servers close a session after a policy limit (time, message count, etc.) and return 421 Service not available, closing transmission channel, or simply close the connection mid-DATA.

In these cases, the SMTP connection is no longer valid and must not be reused.

This PR improves RFC-5321 compliance by:

• discarding pooled connections on terminal SMTP / transport errors
• retrying the message once on a fresh connection

This behavior is SMTP-generic and benefits all providers that enforce session limits.

That framing is very strong.

---

7. Why maintainers are likely to accept this

Because:

• It’s protocol-correct
• It fixes real production failures
• It doesn’t add knobs or complexity
• It matches how mature MTAs behave
• It improves reliability for everyone

---

8. After this PR lands (next step)

Then you can safely add:

MaxMessagesPerConn int

as an optimization, not a correctness fix.

That second PR becomes optional but very useful.

---

9. If you want, I can…

If you want, next message I can:

• write the exact diff against current knadh/smtppool
• adapt it precisely to their struct names
• sanity-check concurrency correctness
• help you anticipate reviewer feedback

Just say “give me the smtppool diff” and I’ll generate it.

[MaximilianKohler]

I uploaded the full code to GPT and it said:

Excellent, thanks for uploading the full smtppool code — this makes it very clear how to proceed. You were also right to question my earlier mention of conn.go; in this repo everything is in pool.go, and that’s exactly where the fix belongs.

Below is a precise, code-aware plan for a clean, upstream-acceptable PR, based on the actual structure of knadh/smtppool.

---

1. Where the bug actually is (now that we’ve seen the code)

The problem is not in listmonk and not in retry count logic.

The real issue is here:

func (p *Pool) Send(e Email) error {
    ...
    retry, err := c.send(e)
    if err == nil {
        _ = p.returnConn(c, nil)
        return nil
    }

    // Not a retriable error.
    _ = p.returnConn(c, err)
    if !retry {
        return err
    }
}

and here:

func (p *Pool) returnConn(c *conn, lastErr error) (err error) {
    if lastErr != nil {
        // Any error, except textproto.Error, is a bad connection
        if _, ok := lastErr.(*textproto.Error); !ok {
            return lastErr
        }
    }

    // Reset and reuse the connection
    if err := c.conn.Reset(); err != nil {
        return err
    }

    p.conns <- c
}

Why this breaks with SES (and others)

• SES returns 421 and closes the TCP connection
• The error returned is often a *textproto.Error
• returnConn() incorrectly treats that as safe to reuse
• Reset() fails or silently reuses a dead socket
• The same broken connection keeps getting reused
• Retries never escape the dead session

This is SMTP-incorrect behavior, regardless of SES.

---

2. What the PR must do (minimal, correct fix)

The rule (RFC-correct, provider-agnostic)

If the SMTP server closes the connection (421 or EOF), that connection MUST be discarded and never reused.

So the fix is:

Treat 421 and EOF as terminal connection errors, even if they are *textproto.Error.

---

3. Exact changes to make (this is the PR)

Step 1: Add a helper to detect terminal SMTP errors

Add this near canRetry() at the bottom of pool.go:

func isTerminalConnErr(err error) bool {
	if err == nil {
		return false
	}

	// RFC 5321: 421 = Service not available, closing transmission channel
	var tpErr *textproto.Error
	if errors.As(err, &tpErr) && tpErr.Code == 421 {
		return true
	}

	// Connection-level failures
	if errors.Is(err, io.EOF) {
		return true
	}

	var netErr net.Error
	if errors.As(err, &netErr) {
		return true
	}

	return false
}

Why this is correct:

• Uses SMTP status code, not string matching
• Uses standard Go error inspection
• No SES references

---

Step 2: Fix returnConn() so dead connections are never reused

Modify returnConn() like this:

Original

if lastErr != nil {
	if _, ok := lastErr.(*textproto.Error); !ok {
		return lastErr
	}
}

Replace with

if lastErr != nil {
	if isTerminalConnErr(lastErr) {
		return lastErr
	}
	if _, ok := lastErr.(*textproto.Error); !ok {
		return lastErr
	}
}

This ensures:

• 421 always kills the connection
• EOF always kills the connection
• Other textproto.Error cases behave as before

---

Step 3: No changes needed in Send()

This is important.

Send() already does the right thing:

• retries on retryable errors
• calls returnConn() correctly
• creates new connections when needed

Once returnConn() stops recycling dead connections, existing retry logic works correctly.

---

4. What NOT to change (important)

Do not:

• change canRetry()
• add provider detection
• add config options
• add message counters
• change retry counts

That keeps the PR:

• small
• obvious
• safe
• upstreamable

---

5. Why this fixes your SES 421 issue

Flow after patch:

1. SES hits message/session limit
2. SES returns 421 and closes connection
3. c.send() returns *textproto.Error{Code:421}
4. returnConn() sees terminal error
5. Connection is closed and discarded
6. Retry opens a new SMTP session
7. Send succeeds

This works for:

• SES
• Postfix
• Exchange
• Gmail SMTP
• Any MTA enforcing session limits

---

6. How to frame the PR (very important)

PR title

Discard pooled SMTP connections on terminal SMTP errors

PR description (you can copy this)

Some SMTP servers close a session after policy limits (e.g. time or message count) and return 421 Service not available, closing transmission channel, or close the connection mid-DATA.

In these cases the SMTP connection is no longer usable and must not be returned to the pool.

This change improves RFC-5321 compliance by treating 421 and connection-level errors as terminal, ensuring dead connections are discarded and retried on fresh connections.

No SES mention. No hacks. Pure protocol correctness.

---

7. After this PR lands (next step)

Only after this is merged does it make sense to add:

MaxMessagesPerConn

That would be an optimization PR, not a correctness fix.

---

8. If you want, I can…

If you want next, I can:

• write the exact diff (git diff) for pool.go
• add a unit test reproducing a 421 close
• help you respond to maintainer feedback

Just tell me what you want next.

[knadh]

Fixed the 421 exception here in a much simpler manner: 24a1bf6

[MaximilianKohler]

Thank you!

To use the update in listmonk, would we need to wait till the next version of knadh/smtppool is released, and then wait again for the next knadh/listmonk release that integrates the update from knadh/smtppool?

IE: listmonk doesn't automatically integrate/use updates from knadh/smtppool into existing versions right?

[knadh]

Yes, it will be in the next release.

But, I'm planning to soon setup an automated weekly release system (like Firefox has Firefox-nightly) that'll create a special release (tagged listmonk-weekly) with whatever changes have been merged. This will allow faster access to changes without having to wait for large consolidated releases.

[rsolvang]

Is there a way to solve this in the meantime with a dirty hack or something?

I have recently started using listmonk on a PikaPod (so have no access to the shell) and discovered this bug just now as our petition (with an optional newsletter signup) went live. Do not look forward to manually resend hundreds of opt-in emails 😅

[knadh]

This is now available as a nightly release. Going forward, all changes on the master branch will be auto-built as a nightly release.

https://listmonk.app/docs/installation/#nightly

[MaximilianKohler]

I see the nightly releases for listmonk, but smtppool still says the last release was a year ago. For this fix to take effect in listmonk, we'll have to wait for the next smtppool release, and then the subsequent listmonk release right?