{"record":{"id":"a36e37f8d9a633ab","repo":"appwrite/appwrite","slug":"the-server-does-not-offer-smtputf8-so-a-non-ascii-address","errorCode":null,"errorMessage":"The server does not offer SMTPUTF8, so a non-ASCII address cannot be sent","messagePattern":"The server does not offer SMTPUTF8, so a non-ASCII address cannot be sent","errorType":"exception","errorClass":"CapabilityException","httpStatus":null,"severity":"error","filePath":"packages/smtp/src/Client.php","lineNumber":381,"sourceCode":"            $size = \\strlen($content);\n            $max = $this->capabilities->maxSize();\n\n            if ($max !== null && $size > $max) {\n                throw new CapabilityException(\"The message is {$size} bytes and the server takes at most {$max}\");\n            }\n\n            if ($this->capabilities->has('SIZE')) {\n                $parameters .= \" SIZE={$size}\";\n            }\n\n            if (! Encoding::isAscii($content) && $this->capabilities->has('8BITMIME')) {\n                $parameters .= ' BODY=8BITMIME';\n            }\n        }\n\n        if ($envelope->isInternational()) {\n            if (! $this->capabilities->has('SMTPUTF8')) {\n                throw new CapabilityException('The server does not offer SMTPUTF8, so a non-ASCII address cannot be sent');\n            }\n\n            $parameters .= ' SMTPUTF8';\n        }\n\n        return $parameters;\n    }\n\n    /**\n     * Normalise line endings, double any leading dot, and close with the\n     * terminator.\n     *\n     * The state carried between chunks is the point: a chunk ending in CRLF\n     * followed by one opening with a dot has to be stuffed as though it were\n     * one string, and a chunk ending mid-CRLF must not be read as a bare CR.\n     *\n     * @param  iterable<string>  $chunks\n     * @return \\Generator<string>","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/appwrite/appwrite/blob/7eab5f1970bacb06f8cce069c27b7d14a4178153/packages/smtp/src/Client.php#L363-L399","documentation":"If the envelope contains international (non-ASCII) addresses (envelope->isInternational()), the client requires the SMTPUTF8 extension. When the server does not advertise SMTPUTF8 in its capabilities, CapabilityException is thrown before the message is sent.","triggerScenarios":"Sending to/from addresses containing non-ASCII characters (e.g. üser@example.com, 日本@example.jp) against an SMTP server without SMTPUTF8 support.","commonSituations":"Modern internationalized email addresses sent through older relays or self-hosted MTAs without SMTPUTF8 enabled; legacy corporate Exchange servers.","solutions":["Enable SMTPUTF8 on the SMTP server if it supports it (Postfix smtputf8_enable=yes, etc.).","Use an ASCII-equivalent (IDA-safe) address or an ASCII alias for the recipient.","Upgrade or replace the relay with one supporting RFC 6531.","Guard in caller code: check envelope->isInternational() and capabilities()->has('SMTPUTF8') before sending."],"exampleFix":"// before\n$client->send($internationalEnvelope); // throws on legacy server\n// after\nif ($envelope->isInternational() && !$client->capabilities()->has('SMTPUTF8')) {\n    $envelope = $envelope->withAsciiFallbackAddresses();\n}\n$client->send($envelope);","handlingStrategy":"validation","validationCode":"if ($envelope->isInternational() && !$client->capabilities()->has('SMTPUTF8')) {\n    throw new DomainException('Server lacks SMTPUTF8; use ASCII addresses');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $client->send($envelope);\n} catch (CapabilityException $e) {\n    if (str_contains($e->getMessage(), 'SMTPUTF8')) {\n        // resend with ASCII-equivalent addresses\n    }\n}","preventionTips":["Normalize recipient addresses to ASCII where possible","Enable SMTPUTF8 on servers that handle international addresses","Check the extension list before sending internationalized mail"],"tags":["smtp","email","utf8","i18n"],"backgroundTag":"unsupported-operation","analyzedSha":"7eab5f1970bacb06f8cce069c27b7d14a4178153","analyzedAt":"2026-09-23T00:38:38.905Z","contentChangedAt":"2026-09-23T00:38:38.905Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}