appwrite/appwrite · error · CapabilityException
The server does not offer SMTPUTF8, so a non-ASCII address…
Error message
The server does not offer SMTPUTF8, so a non-ASCII address cannot be sent
What it means
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.
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.
Example fix
// before
$client->send($internationalEnvelope); // throws on legacy server
// after
if ($envelope->isInternational() && !$client->capabilities()->has('SMTPUTF8')) {
$envelope = $envelope->withAsciiFallbackAddresses();
}
$client->send($envelope); Defensive patterns
Strategy: validation
Validate before calling
if ($envelope->isInternational() && !$client->capabilities()->has('SMTPUTF8')) {
throw new DomainException('Server lacks SMTPUTF8; use ASCII addresses');
} Try / catch
try {
$client->send($envelope);
} catch (CapabilityException $e) {
if (str_contains($e->getMessage(), 'SMTPUTF8')) {
// resend with ASCII-equivalent addresses
}
} Prevention
- Normalize recipient addresses to ASCII where possible
- Enable SMTPUTF8 on servers that handle international addresses
- Check the extension list before sending internationalized mail
When it happens
Trigger: Sending to/from addresses containing non-ASCII characters (e.g. üser@example.com, 日本@example.jp) against an SMTP server without SMTPUTF8 support.
Common situations: Modern internationalized email addresses sent through older relays or self-hosted MTAs without SMTPUTF8 enabled; legacy corporate Exchange servers.
Understand the failure class
Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.
Related errors
- A message needs at least one recipient
- A subject must not span lines
- Address is over the length limits of RFC 5321
- An address must not span lines
- An attachment name, type or identifier must not span lines
AI-assisted analysis of appwrite/appwrite@7eab5f1970 (2026-09-23).
Data as JSON: /api/errors/a36e37f8d9a633ab.
Report an issue: GitHub.
Appendix: source
Thrown at packages/smtp/src/Client.php:381
$size = \strlen($content);
$max = $this->capabilities->maxSize();
if ($max !== null && $size > $max) {
throw new CapabilityException("The message is {$size} bytes and the server takes at most {$max}");
}
if ($this->capabilities->has('SIZE')) {
$parameters .= " SIZE={$size}";
}
if (! Encoding::isAscii($content) && $this->capabilities->has('8BITMIME')) {
$parameters .= ' BODY=8BITMIME';
}
}
if ($envelope->isInternational()) {
if (! $this->capabilities->has('SMTPUTF8')) {
throw new CapabilityException('The server does not offer SMTPUTF8, so a non-ASCII address cannot be sent');
}
$parameters .= ' SMTPUTF8';
}
return $parameters;
}
/**
* Normalise line endings, double any leading dot, and close with the
* terminator.
*
* The state carried between chunks is the point: a chunk ending in CRLF
* followed by one opening with a dot has to be stuffed as though it were
* one string, and a chunk ending mid-CRLF must not be read as a bare CR.
*
* @param iterable<string> $chunks
* @return \Generator<string>View on GitHub (pinned to 7eab5f1970)