SMTP Status Codes Need Context, Not Guesswork

SMTP replies such as 250, 451, and 550 are often treated as simple success-or-failure labels. In real delivery systems, they are more useful as inputs to a decision process: should a message be retried, stopped, investigated, or classified for support and analytics?

The Open SMTP Error Dataset is a machine-readable reference for interpreting SMTP delivery outcomes consistently. It contains 92 English-language SMTP enhanced-status records and is available in JSON Lines, CSV, and Parquet formats.

Each record connects a status code with a practical category, outcome class, diagnostics, and suggested operational handling. The goal is to make SMTP status information useful both to people debugging an issue and to systems processing bounces at scale.

Code first, text second

The most reliable way to classify a bounce is by its enhanced status code.

• 250 2.1.5 — successful recipient delivery outcome.
• 451 4.4.1 — temporary delivery condition; retry logic may be appropriate.
• 550 5.1.1 — permanent recipient-related outcome for that delivery attempt.

A 4.x.x status is not an instruction to retry forever, and a 5.x.x status is not automatically a reason to permanently remove an address. A useful delivery system combines the code with queue age, retry limits, recipient history, provider context, and its own sending policy.

Diagnostic text is useful when no enhanced code is available, but it should be treated as a signal rather than a certainty. Phrases such as “user unknown”, “temporarily unavailable”, or “message too large” can direct an investigation without inventing a code or making an irreversible decision.

What the dataset includes

The release contains:

• 92 structured SMTP enhanced-status records
• JSONL, CSV, and Parquet data files
• A JSON Schema for validation
• Exact-code recognition rules
• Text-signal rules for incomplete bounce responses
• Examples for code-based and text-based recognition
• A manifest for checking package contents

This makes the dataset useful for bounce processors, email platforms, observability pipelines, support tools, data analysis, and developer documentation.

A practical processing pattern

A safe bounce-processing flow is straightforward:

1. Extract the SMTP reply and enhanced status code from the delivery response.
2. Match the exact enhanced code when it is present.
3. Use the matched record to classify the outcome and select the next action.
4. If only text is available, return a cautious text-based signal instead of guessing.
5. Keep unmatched or contradictory responses available for review.

This approach produces cleaner reporting than a single “email failed” metric. Teams can track temporary conditions, permanent delivery outcomes, authentication issues, message-size limits, and route-specific problems separately.

Dataset links

Hugging Face:

https://huggingface.co/datasets/blazalek/open-smtp-error-dataset

Zenodo DOI:

https://doi.org/10.5281/zenodo.21717985

Interactive SMTP error catalog:

https://blazalek.com/en/email-errors

Disclosure: Blazalek maintains the Open SMTP Error Dataset and the linked SMTP error catalog.