RocketChat/Rocket.Chat · error · MeteorError

error-email-send-failed

error-email-send-failed

Error message

SMTP is not configured

What it means

Thrown by users.sendWelcomeEmail when isSMTPConfigured() is false. The endpoint cannot send mail because no SMTP server is configured, so it fails fast rather than silently dropping the welcome email.

Source

Thrown at apps/meteor/server/api/v1/users.ts:853

		permissionsRequired: ['send-mail'],
		response: {
			200: ajv.compile<void>({
				type: 'object',
				properties: {
					success: { type: 'boolean', enum: [true] },
				},
				required: ['success'],
				additionalProperties: false,
			}),
			400: validateBadRequestErrorResponse,
			401: validateUnauthorizedErrorResponse,
		},
	},
	async function action() {
		const { email } = this.bodyParams;

		if (!isSMTPConfigured()) {
			throw new MeteorError('error-email-send-failed', 'SMTP is not configured', {
				method: 'sendWelcomeEmail',
			});
		}

		const user = await Users.findOneByEmailAddress(email.trim(), { projection: { name: 1 } });

		if (!user) {
			throw new MeteorError('error-invalid-user', 'Invalid user', {
				method: 'sendWelcomeEmail',
			});
		}

		await sendWelcomeEmail({ ...user, email });

		return API.v1.success();
	},
);

View on GitHub (pinned to f9d3ec372b)

Solutions

  1. Configure SMTP (Admin > Email > SMTP) with a valid host/port/user/pass, then retry.
  2. Verify connectivity from the server to the SMTP host (firewall, DNS, credentials).
  3. Use the 'Send a test email' admin action to confirm SMTP works before calling the endpoint.

Example fix

null
Defensive patterns

Strategy: validation

Validate before calling

// Check SMTP readiness via admin settings before offering the action
const smtp = await GET('settings.smtp');
if (!smtp || !smtp.host) { showSMTPWarning(); return; }

Type guard

null

Try / catch

try {
  await POST('users.sendWelcomeEmail', { email });
} catch (e) {
  if (isMeteorError(e, 'error-email-send-failed')) {
    // prompt admin to configure SMTP, then retry
  } else { throw e; }
}

Prevention

When it happens

Trigger: POST users.sendWelcomeEmail before Email / SMTP settings have been populated (host, port, credentials).

Common situations: Fresh install without email setup; SMTP settings cleared during migration; environment-specific config not applied.

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@f9d3ec372b (2026-08-12). Data as JSON: /api/errors/e483721e50c9d7b9. Report an issue: GitHub.