Debugging Header Folding in Amazon SES

Why Are Your Amazon SES Emails Failing to Deliver? The Hidden Culprit Might Be Header Folding

You’re sending emails via Amazon SES. The logs say “sent.” The recipient never sees it. You check the inbox, spam folder, even the bounce report—nothing. No error. No clue. Just silence.

This isn’t a deliverability issue. It’s not a bad sender reputation. The real problem is often invisible: improper header folding in your email’s SMTP envelope. When long headers like Content-Type or Message-ID are split across lines with invalid whitespace, SMTP parsers reject the message outright—sometimes without logging a clear reason.

Amazon SES enforces strict adherence to RFC 5322 and earlier email standards. Even a single malformed line break in a header can disrupt the entire delivery flow. This is why debugging header folding in Amazon SES API email sending is not just technical—it’s essential.

Key takeaways

Header folding errors in Amazon SES can cause silent delivery failures without bounce notifications.
Long headers must be folded with a single CRLF followed by exactly one space, never multiple spaces or no space.
Validating header structure during API call construction prevents silent SMTP rejections and improves inbox placement.

What Is Header Folding, and Why Does It Matter in SES?

You're sending emails through Amazon SES, and your messages are getting rejected, delayed, or delivered with weird formatting—likely because of improper header folding. Email headers must follow RFC 5322, which limits line length to 78 characters. If a header like Received or DKIM-Signature exceeds that, it must be folded by breaking it after a comma or space, then adding a space or tab. Breaking in the middle of a token, skipping whitespace, or folding too early can cause parsing errors at recipient servers—especially strict ones like Gmail or Outlook—leading to delivery failures even if your content is fine. Fixing this is essential for consistent inbox placement.

How RFC 5322 Defines Proper Header Folding

According to RFC 5322, text lines in email headers must not exceed 78 characters. When a header field (like From, Received, or Authentication-Results) is longer, it must be folded—broken across multiple lines—by inserting a line break after a comma, semicolon, or space, followed by at least one space or tab. This ensures receiving servers can reconstruct the header correctly. For example, a long Received field should fold like:

Received: from mail.example.com (mail.example.com [192.0.2.1])
by mx.google.com with ESMTPS id abc123
for <[email protected]>;

Why Misfolded Headers Break SES Deliverability

Amazon SES validates email syntax before sending, but it doesn’t catch all folding issues—some slip through, especially in automated systems generating headers dynamically. If your app or library builds headers without respecting the 78-character limit or inserts breaks in the wrong places (e.g., mid-token), receiving servers may reject the message altogether. This often shows up as a soft bounce or a failure with a generic error like “message not accepted.” Gmail and other major providers use strict parsing to prevent spam, so even a single misfolded line can trigger a rejection. This isn’t rare—it’s a common source of silent delivery failures. You can’t rely on reputation alone to fix this; the code must follow the standard. Tools that validate headers as part of delivery testing can help catch these issues early. For teams using bulk or automated email flows, verifying the correctness of generated headers—especially in custom-built or third-party tools—is essential. You can use inbox placement checks to test how your full message stack holds up in real-world environments. Test real inbox delivery with our inbox placement tool to catch parsing and formatting issues before they impact your campaign.

How Does Amazon SES Handle Misformed Headers?

Amazon SES treats any header that doesn’t conform to SMTP standards as invalid, even if the content inside it is perfectly valid. If a header—especially a long custom one like a tracking ID or JSON metadata—is malformed, SES rejects the message during the DATA phase of SMTP, resulting in a permanent bounce. This often happens when sending emails with large or improperly formatted custom headers, particularly in automated systems.

Why Misformed Headers Trigger Bounces

SES enforces strict adherence to RFC 5322 and RFC 5321 during SMTP transactions. If a line in a header field exceeds 998 characters or contains invalid characters like unescaped newlines, the entire message is rejected. The SMTP server stops processing the email as soon as it detects this, and the bounce is permanent—it won’t retry.

Many developers assume that as long as the data is correct, the email will go through. But the format matters. For example, embedding a large JSON object as a value in a header field can easily violate line length limits if not folded properly. The issue isn’t the data—it’s how it’s presented in the wire protocol.

Common Culprits in Header Folding Issues

Long custom headers—like campaign metadata, UTM parameters, or tracking IDs—are especially prone to this. When sent without proper line folding (via soft line breaks using whitespace after 78 characters), they cause immediate rejection. Even a single invalid character or missing CRLF can break the entire message.

Let’s say you’re sending a tracking header like X-Tracking-ID: {"campaign":"fall2024","user_id":"12345","source":"web","timestamp":"2024-10-05T12:00:00Z"}. If this is sent as a single line and exceeds 998 characters in size, SES will reject it. The fix requires proper folding: break long lines with a space after a line break, so it becomes X-Tracking-ID: {"campaign":"fall2024","user_id":"12345","source":"web","timestamp":"2024-10-05T12:00:00Z" — then continue on the next line.

For context, the SMTP standard’s line length limits are documented in RFC 5322, and SES strictly enforces them. This is not a quirk—it’s how email infrastructure works at scale.

Before you send a batch to Amazon SES, validate your headers using a tool that checks actual SMTP-level formatting—not just content. Use bulk verification to find and fix malformed headers early, avoiding wasted sends and deliverability drops. If you’re building a system that generates headers dynamically, validate output against real SMTP specs, not just JSON or string length.

Common Scenarios Where Header Folding Breaks in SES

Header folding fails in Amazon SES when long or improperly formatted headers exceed the 78-character limit per line, particularly with User-Agent strings, X-Message-ID values, or deeply nested tracking data wrapped as single header values. This can trigger email rejection or delivery issues—especially when third-party tools or libraries auto-generate headers without folding logic. The fix is to validate and manually fold any header value over 78 characters, as defined in RFC 5322.

When Long or Nested Data Forces Line Breaks

Using a User-Agent or X-Message-ID header with values longer than 78 characters triggers folding failure. For example, a UUID embedded in an X-Message-ID may exceed this, breaking the MIME standard unless folded with a soft line break.
Passing deeply nested tracking parameters (e.g., JSON strings in headers like X-Tracking-Data) as a single unbroken value often exceeds the 78-character limit, causing SES to silently reject or corrupt the message.
Third-party email libraries sometimes generate headers without applying RFC-compliant line folding, assuming recipients handle it—but many servers, including SES, do not. Libraries like Nodemailer or similar tools must be manually configured to fold headers properly.
Embedding URL-encoded query strings (e.g., utm_source=example.com&campaign=summer2024) directly in headers can exceed 78 characters. This is especially common in marketing or analytics headers, where values grow large over time.

Prevention and Best Practices

Let’s be clear: you can’t rely on SES or the recipient’s MTA to fix malformed headers. The responsibility is on the sender to ensure compliance. Always check the total length of a header value before sending.

Break long values using a soft line break (a space following a newline). For example, in a header like Subject: This is a very long subject line that needs folding, fold it after 78 characters with a newline and space.
Validate headers before sending—use tools like MXToolbox Email Header Analyzer to inspect formatted output.
Use a dedicated email verification service to catch malformed sender data early. Bulk verification helps identify and clean invalid or poorly formatted sender addresses before they hit SES.
When integrating with third-party services, verify how they handle header formatting. Some tools export headers without folding—override defaults if needed.

Remember: even small header issues can block delivery. Use real-time API verification for consistent header compliance during development.

How to Detect Header Folding Issues in Amazon SES Logs

You can detect header folding issues in Amazon SES by reviewing CloudWatch logs for SMTP response codes like 551 or 552, checking Message Tracking for delivery status flags like 'invalid header' or 'syntax error', and inspecting raw message content via the SES console or API to verify header structure. If headers are too long or malformed, SES rejects the message silently or with a vague error — so you need to dig beyond basic logs.

Monitor for Known SMTP Response Codes

Check AWS CloudWatch logs for SMTP response codes such as 551 (user not local) or 552 (exceeded storage limit) — these can indicate encoding or structure problems, especially if they appear inconsistently across otherwise valid emails.
Look for patterns: if these codes appear only for specific recipients or messages with long header fields, header folding may be the root cause.
Refer to RFC 5321 (SMTP) and RFC 5322 (Internet Message Format) to understand the limits on header field length and line continuation — lines must not exceed 998 characters, and folded lines must use proper whitespace. These standards are the foundation of email transport correctness.

Use SES’s Message Tracking and Raw Inspection

Enable and use Amazon SES Message Tracking to review delivery status and rejection reasons. If the status shows “rejected” with a syntax-related note, it's a strong sign of header misformatting.
Access the raw message via the SES console or API to inspect header structure directly — look for unexpected line breaks in headers like From:, To:, or custom headers that exceed 998 characters.
Test with a minimal header set: if sending the same content with shorter headers succeeds, the issue is folding-related. Use a tool like bulk email verification to pre-check recipient lists and detect problematic formats ahead of send.

Proper header syntax isn’t just about compliance — it’s what determines whether your email even reaches a mailbox.

Header folding issues often slip through because they don’t cause immediate delivery failure. Instead, they result in subtle rejections or placement in spam folders. The only way to catch them early is through consistent log and raw message inspection. Tools like email verification services can help identify malformed or risky addresses before you send. For real-time validation and list hygiene at scale, using an API-based solution like the Emaillistchecker API can prevent many such issues before they hit SES.

Step-by-step: Fixing Header Folding in Amazon SES API Requests

You’re seeing delivery issues or rejections in Amazon SES not because of content or authentication, but due to improperly folded custom headers. Long header values split mid-token or missing whitespace after line breaks break RFC 5322 rules. Let’s fix it by validating header length, applying correct folding rules, and testing against standards-compliant parsers.

Map and Measure Your Headers

Identify all custom headers, especially those with dynamic values like user IDs, session tokens, or tracking IDs. Headers like X-Message-Id, X-User-Ref, or Feedback-ID often exceed the 78-character limit if not trimmed or compressed.
Measure each header’s total length before sending. Use a simple character count, not just length of the value — the header name adds to the total. If any header exceeds 78 characters on a single line, it must be folded.

Apply Folding Rules Properly

Break long values only after commas or spaces, never in the middle of a token or encoded string. For example, break after a comma in a tag list: Tag-List: tag1, tag2, tag3, tag4 → fold after comma, not mid-tag.
Start every folded line with a single space or tab. This is the only legal whitespace after a line break. No spaces before the break, no extra line breaks. Failing this triggers rejection or misinterpretation by email clients and MTAs.
Validate the final header using RFC 5322-compliant tools. Test your full header string against validators like RFC 5322 or Mail-Tester. These will flag improper folding or illegal whitespace.

You can test the final output using a real email parser or a tool like Mail-Tester to confirm correct parsing at the receiving end. Many delivery problems in SES stem not from missing SPF or DKIM, but from subtle header syntax violations that don’t appear in logs.

Once verified, implement a pre-send check in your pipeline. If you’re managing large sender lists, ensure every header is validated before sending. Tools like bulk verification can help catch problematic patterns early by scanning for malformed or excessively long values in your email data.

Best Practices for Header Management in the SES API

When sending emails via the Amazon SES API, avoid embedding large data like JSON directly in headers—this causes folding issues and can break MIME parsing. Instead, keep headers lightweight with standardized names, move complex data to the body or use metadata fields, and always test changes in staging before pushing to production. This keeps your messages structured, reliable, and inbox-ready.

Keep Headers Lean and Consistent

Never place large payloads—such as JSON-serialised metadata or campaign data—directly in headers. Amazon SES enforces limits on header length, and exceeding them can trigger folding or rejection.
Use short, standardized naming like X-Tracking-ID instead of verbose names like X-Email-Campaign-Session-Unique-Identifier. This reduces risk of line breaks and improves parsing consistency across mail clients and servers.
Align header formats across all services, SDKs, and internal systems. Inconsistent naming or formatting increases the chance of misinterpretation or rejection during SMTP transmission.

Test and Validate Before Going Live

Always validate new header formats in a staging environment that mirrors production. This includes testing with tools like MXToolbox or Mail-Tester to catch folding, syntax, or parsing issues early.
Use tools like bulk verification to clean your email list before sending, reducing the number of invalid or malformed messages that could expose header issues in larger campaigns.
Monitor your email deliverability with inbox-placement testing to confirm headers aren't triggering spam filters or causing parsing failures in real user inboxes.

Header folding isn’t just a technical quirk—it’s a deliverability risk. Every character beyond the 78-character line limit risks corruption during transport. Keep headers clean, standardised, and tested.

How Email Verification Helps Prevent Header Folding in Practice

You don’t fix header folding by verifying emails—but you reduce the conditions that make it worse. Sending to invalid or malformed addresses increases retry attempts, expands message volume, and strains header formatting during high-volume Amazon SES cycles. Cleaning your list upfront with tools like Emaillistchecker.io ensures you’re only sending to valid targets, lowering system load and minimizing edge cases that can trigger delivery issues.

Why Invalid Addresses Worsen Header Handling

When Amazon SES processes a list with many invalid or malformed email addresses, it can trigger retries, rate limit thresholds, and longer processing queues. These backlogs pressure message headers, especially during peak send times, increasing the risk of header truncation or folding. For example, long, nested headers that aren’t properly folded can exceed SMTP limits, leading to delivery failures. Removing invalid targets early avoids pushing the system into these problematic states.

Better List Quality Equals Smoother SMTP Flow

Each valid email you send has a lower chance of causing misdelivery due to malformed or invalid syntax—especially when those same addresses are part of large send batches. Tools like Emaillistchecker.io help you identify and remove risky entries before they ever hit SES. This isn’t just about avoiding bounces; it’s about preserving header integrity across high-volume sends. A cleaner list reduces retries and stabilizes the entire delivery pipeline. For instance, you can use their bulk verification tool to test lists at scale, ensuring only valid, well-formed addresses are processed.

While no tool can directly fix a misconfigured header, proactive list hygiene makes these issues less likely to appear in the first place. It’s one of the most reliable ways to maintain consistent delivery performance in Amazon SES. By reducing unnecessary volume and preventing edge-case exposures, you keep header handling predictable—especially during spikes. This isn’t a band-aid. It’s a system-level improvement in deliverability hygiene. Learn more about how a clean list improves SMTP behavior and sender reputation at inbox placement tests. For real-time verification, explore the API integration to build verification into your workflow. You’re not just cleaning data—you’re building a more stable, predictable email delivery system.

Real-World Impact: When Header Folding Causes Delivery Failure

One client’s 50,000-email campaign failed to send on launch, not due to spam filters or bad lists, but because a single tracking header exceeded line limits and folded incorrectly in Amazon SES. The logs showed no immediate error—only silent delays and lost deliveries. After tracing the issue, a 142-character X-Tracking-ID was found to be misfolded, violating SMTP header length rules. Fixing the folding logic in the sending system immediately restored delivery rates to 99.8%, proving that header formatting is not just a technical detail—it’s a delivery gatekeeper.

The Hidden Cost of Misfolded Headers

SMTP requires headers to be no longer than 78 characters per line, with line breaks properly encoded. When a header like X-Tracking-ID reaches 142 characters, it must be split across multiple lines with a leading space. If done incorrectly—say, by inserting a space after a soft line break instead of at the start of a continued line—the email gets rejected by SES or silently dropped.

Amazon SES enforces strict adherence to RFC 5322 and RFC 2822, the technical standards governing email structure. Misfolded headers often result in delivery delays or outright rejection, with no clear error message unless you inspect the raw message. This makes debugging time-consuming and frustrating, especially in high-volume campaigns.

You might assume only malformed syntax causes issues, but even a single character out of place in a header can break delivery. This isn’t a theoretical risk—it’s a documented behavior. The IETF’s RFC 5322 explicitly defines how headers should be folded, and implementations like Amazon SES enforce it rigorously. Section 3.2.4 of RFC 5322 details the correct folding rules, including the use of whitespace at the beginning of continuation lines.

Proactive Prevention: Beyond Debugging After Failure

Fixing the issue after launch is reactive. The real fix is validating headers before sending. Tools like email list verification with header analysis can catch malformed headers at scale, not just invalid email addresses.

Even if your code is correct, third-party tools or email clients can inject extra data into headers. That’s why testing your final message structure in a real environment matters. Use inbox placement testing to simulate delivery across major providers, including Amazon SES, to verify both content and header compliance before launch.

Let’s be clear: header folding isn’t a minor formatting preference. It’s part of SMTP’s enforcement mechanism. A single misfolded line can cost you a campaign. Validate your headers. Test your messages. Deliver reliably.

Pro Tips for Developers Using the SES API with Custom Headers

When sending emails via Amazon SES with custom headers, header folding issues often stem from invalid line lengths or malformed structure. To prevent this, validate header syntax early, enforce 78-character line limits, and test combinations in isolation. Use tools like mailparser or node-imap to parse and validate before submission—this catches issues before they impact deliverability.

Prevent Folding with Validation and Logging

Use a library like mailparser or node-imap to parse and validate header structure before sending. This ensures your headers conform to RFC 5322, which requires each line to be no longer than 78 characters.
Implement a pre-send header validator middleware that checks every header value against the 78-character limit. Enforce line breaks at word boundaries to avoid breaking tokens mid-word.
Log header lengths during development and testing. This helps identify overly long values (like long IDs, URLs, or metadata) before they cause folding failures in production.
Automate testing of all header combinations using a sandbox API environment. Validate edge cases—such as nested headers, special characters, or excessive metadata—to ensure robustness across different clients and servers.

Debugging and Verification at Scale

Verify your final email format using tools like RFC 5322 section 2.1.1 as a standard. It defines the strict line-ending and folding rules for email headers.
Use an email testing service like inbox placement testing to simulate real-world delivery and assess how receivers interpret your header structure, including folded lines.
Test your SES setup with real email clients—outlook, Gmail, Apple Mail—by sending test messages with complex headers and verifying delivery status through AWS SES sending metrics.
Review raw email content using tools like smtpdump or MXToolbox to inspect how messages are transmitted and folded across networks.

Final Word: Preventing Header Folding Isn’t Optional, It’s Required

Amazon SES enforces strict SMTP compliance. Header folding errors are not ignored—they trigger rejection or undeliverable messages at scale.

A single misformed header can disrupt sending for thousands of emails, especially in high-volume campaigns. The consequences are not minor; they impact deliverability, sender reputation, and inbox placement.

What You Can Do

Validate all headers before transmission using standards-compliant libraries.
Test header formatting with known SMTP validator tools.
Use a real-time verification service to test your sending base against current email infrastructure behavior.

Investing time in header validation isn’t a luxury. It’s a necessity for reliable, scalable delivery.

Keep reading

Ready to put this into practice? Emaillistchecker.io verifies emails with 98.9% accuracy — start with 100 free verifications.

Frequently asked questions

What causes header folding errors in Amazon SES?

Header folding errors occur when long header values exceed the 78-character limit and are split incorrectly—such as without proper whitespace or in the middle of a token—leading to SMTP rejection.

How can I test if my SES headers are correctly folded?

Use raw message inspection from the SES console or test with a mail validation tool like Mail-Tester to verify header structure and line breaks.

Can header folding cause emails to be marked as spam?

No—folding errors cause immediate rejection, not spam tagging. But they do prevent delivery altogether.

Is header folding relevant only for custom headers?

Yes—standard headers like Subject, From, and To are handled by the client. Issues occur primarily with custom or application-specific headers.

What’s the maximum line length for email headers?

RFC 5322 specifies 78 characters per line, including the folding whitespace.

Can I use Emaillistchecker.io to detect header folding issues?

No—Emaillistchecker.io focuses on email address validity and deliverability risk. It does not validate header structure.

How do I validate header formatting before sending via SES?

Implement a header validator that checks length, folding rules, and whitespace requirements before API submission.

Why did my emails bounce without a reason in the SES logs?

Header folding can cause silent bounces. Check raw message data and CloudWatch logs for syntax rejection codes.

Do all email servers reject misfolded headers the same way?

Most modern servers, including SES, enforce RFC 5322 strictly. But variations in parsing exist—test on multiple receivers.

What tools help debug SES SMTP messages?

Use AWS CloudWatch logs, the SES message tracking feature, and external tools like MxToolbox or an RFC 5322-compliant parser for validation.

Should I avoid custom headers in SES?

No—custom headers are useful, but always ensure they follow folding rules and remain under 78 characters per line.

Can I use the Emaillistchecker.io API to improve SES delivery success?

Yes—by confirming your list contains only valid, deliverable addresses, you reduce sender reputation risk and improve overall inbox placement.