TryGhost/Ghost · error · EmailError

Please verify your email settings

Error message

Please verify your email settings

What it means

EmailError, thrown by handleResponse when errors[0].type === 'EmailError'. It signals that an email-sending operation failed because of misconfigured or unavailable mail transport (Mailgun, SMTP, etc.). The specific transport error detail is in error.data.

Source

Thrown at apps/admin-x-framework/src/utils/api/handle-response.ts:37

            throw new APIError(response, await response.text());
        }

        const data = await response.json() as ErrorResponse;

        if (response.status === 403 && data.errors?.[0]?.message === 'Authorization failed') {
            throw new UnauthorizedError(response, data);
        } else if (data.errors?.[0]?.type === 'VersionMismatchError') {
            throw new VersionMismatchError(response, data);
        } else if (data.errors?.[0]?.type === 'ValidationError') {
            throw new ValidationError(response, data);
        } else if (data.errors?.[0]?.type === 'NoPermissionError') {
            throw new ValidationError(response, data);
        } else if (data.errors?.[0]?.type === 'ThemeValidationError') {
            throw new ThemeValidationError(response, data);
        } else if (data.errors?.[0]?.type === 'HostLimitError') {
            throw new HostLimitError(response, data);
        } else if (data.errors?.[0]?.type === 'EmailError') {
            throw new EmailError(response, data);
        } else {
            throw new JSONError(response, data);
        }
    } else if (response.status === 204) {
        return;
    } else if (response.headers.get('content-type')?.includes('text/csv')) {
        return await response.text();
    } else {
        return await response.json();
    }
};

export default handleResponse;

View on GitHub (pinned to 47d8b0e2ad)

Solutions

1. Open Ghost Admin → Settings → Labs / config and verify the mail transport settings (Mailgun key+domain or SMTP host/port/user/pass).
2. Send a test email from the admin to confirm the transport works end-to-end.
3. Inspect error.data for the underlying transport message (auth failure, connection refused, etc.) and fix that specific cause.

import {EmailError} from '@tryghost/admin-x-framework/utils/errors';
function isEmailError(e: unknown): e is EmailError {
    return e instanceof EmailError;
}

import {EmailError} from '@tryghost/admin-x-framework/utils/errors';
try {
    await api.users.invite({email});
} catch (e) {
    if (e instanceof EmailError) {
        notify('Email sending failed. Check your mail settings in Labs.');
        // e.data?.errors?.[0]?.message has the transport-specific error
    } else throw e;
}

When it happens

Trigger: Triggering a send — staff invite emails, member signup confirmation, newsletter publishing, magic-link login — while the mail service is misconfigured, has bad credentials, or is unreachable. Ghost returns {errors:[{type:'EmailError', ...}]} with the transport's error.

Common situations: Mailgun API key/region mismatch; SMTP host/port/encryption wrong; email from-address not verified; mail provider rate-limit or outage; DNS (SPF/DKIM) issues surfacing as transport errors.

Related errors

• email.error
• No staff invitation email found for ${email}${detail}
• post.email.error
• Your email has failed to resubscribe, please try again
• Failed to send magic link email

AI-assisted analysis of TryGhost/Ghost@47d8b0e2ad (2026-08-13). Data as JSON: /api/errors/c12e3a901ccb7bc6. Report an issue: GitHub.