How-to: looking up members with a "+" sign in email over API

Integrations & API
1

Some password managers generate unique e-mail addresses for mailing lists and services, in the format user+service@example.com

Ghost API fails when looking up a user with an e-mail containing a “+” sign.

On GitHub user velocity23 found a solution, sharing it here, thank you!

The e-mail first has to be URL-encoded so user+service@example.com becomes user%2Bservice%40example.com and then the API call has to be single quoted

/admin/members/?filter=email%3A'user%2Bservice%40example.com'

… or the API call will fail. Claude explains why…

The need to single-quote an email address containing a “+” sign in an API call is related to how special characters are interpreted in URLs and query parameters. Let’s break this down:

  1. URL encoding:
    The email address is first URL-encoded. This transforms special characters into their percent-encoded equivalents:

    • + becomes %2B
    • @ becomes %40

  2. Query parameter interpretation:
    In many web frameworks and API implementations, the plus sign (+) in a query string is interpreted as a space character. This is a legacy from early web forms where + was used to represent spaces.

  3. Single quotes:
    By enclosing the encoded email in single quotes, you’re telling the API to treat everything inside the quotes as a single value. This prevents the %2B from being misinterpreted as a space or as separate parts of the query.

Without the single quotes, the API might interpret the %2B as a space or as a separator between different parts of the filter, which would lead to incorrect filtering.

So, the single quotes ensure that the entire encoded email address is treated as a single, literal string value in the filter parameter, preserving the + sign (as %2B) in the email address.

This approach allows the API to correctly handle email addresses with special characters while maintaining compatibility with standard URL parsing and query string interpretation.