Track upstream EAI/SMTPUTF8 support for Unicode email local-parts

[sandervanhooft]

Context

#26 / #27 added transparent IDN domain normalization: user@münchen.de is now sent on the wire as user@xn--mnchen-3ya.de. The local-part is intentionally left as-is, because:

1. There is no ASCII encoding for non-ASCII local-parts. Punycode (RFC 3492) is defined for DNS labels only — there is no analogous transformation for everything to the left of @.

2. The only standardized path for Unicode local-parts is EAI / SMTPUTF8 (RFC 6531), which sends UTF-8 over the wire as-is. That requires server-side support.

3. The Vatly API explicitly does not currently support this. From openapi.yaml line 84:

   Local-part Unicode (EAI / SMTPUTF8) is not supported.

So today, a caller passing josé@example.com to any endpoint that accepts an email field will get the API's validation error. The SDK can't transparently fix this — the only honest option is to surface the server's rejection.

What this issue tracks

When the API server adds EAI / SMTPUTF8 support and the spec note at openapi.yaml:84 flips, this SDK should:

• Confirm UTF-8 local-parts pass through BaseEndpoint::parseRequestBody unchanged (they should already — the IDN walker only touches the domain).
• Add a test asserting josé@münchen.de is sent as josé@xn--mnchen-3ya.de (Unicode local-part preserved, domain still punycoded).
• Update the relevant docstrings / README notes that currently say the API rejects Unicode local-parts.
• Update IdnEmailTest::it_leaves_unicode_local_part_untouched — the test name and behavior stay the same, but it's worth a comment noting upstream now accepts what it asserts.

Optional middle-ground (before upstream lands)

If the lack of fail-fast feedback becomes painful, the SDK could detect non-ASCII local-parts at call time and throw a clearer exception locally instead of waiting for the round-trip. Deferred until there's user signal — current behavior (server returns 422 with a meaningful error) is acceptable.

References

• RFC 6531 — SMTP Extension for Internationalized Email
• RFC 6532 — Internationalized Email Headers
• Current SDK behavior: src/API/Support/IdnEmail.php
• Spec note: openapi.yaml:84