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

  1. Enable SMTPUTF8 on the SMTP server if it supports it (Postfix smtputf8_enable=yes, etc.).
  2. Use an ASCII-equivalent (IDA-safe) address or an ASCII alias for the recipient.
  3. Upgrade or replace the relay with one supporting RFC 6531.
  4. 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

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


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)