Troubleshooting

Emails Not Appearing

Check the SMTP Host

The correct hostname is sandbox.mailloop.io:

{
  host: 'sandbox.mailloop.io',
  port: 587,
  auth: {
    user: 'your-sandbox-username',
    pass: 'your-sandbox-password'
  }
}

Verify Credentials

1. Open your sandbox in the dashboard
2. Confirm the username and password match your configuration
3. Check for extra spaces or encoding issues in your credentials

Check Application Logs

Look for errors in your application's SMTP output:

• 535 Authentication failed -- incorrect username or password
• Connection timeout -- network or firewall issue
• SSL routines or certificate verify failed -- TLS configuration issue

Test with curl

Verify your credentials work independently of your application:

curl --url 'smtp://sandbox.mailloop.io:587' \
  --ssl-reqd \
  --mail-from '[email protected]' \
  --mail-rcpt '[email protected]' \
  --user 'your-username:your-password' \
  -T message.txt

Authentication Errors

Error: 535 Authentication failed

• Verify the username and password are correct (copy them fresh from the dashboard)
• Make sure you are using the sandbox username, not your account email
• Check for trailing whitespace in your credentials
• Try resetting the sandbox password from the dashboard

Connection Issues

Error: Connection timeout or Could not connect to SMTP host

Check Your Firewall

Ensure your network allows outbound connections on the SMTP port you are using:

• Port 587 (STARTTLS)
• Port 465 (SSL/TLS)
• Port 25 or 2525 (alternate)

Test Connectivity

telnet sandbox.mailloop.io 587

If this fails, your network may be blocking the connection. Try an alternate port.

Try an Alternate Port

If port 587 is blocked, try port 465 with SSL:

{
  host: 'sandbox.mailloop.io',
  port: 465,
  secure: true,
  auth: {
    user: 'your-sandbox-username',
    pass: 'your-sandbox-password'
  }
}

Port 2525 is also available and is less likely to be blocked by corporate firewalls.

TLS/SSL Errors

Error: SSL routines or certificate verify failed

• Update your SMTP library to the latest version
• Make sure you are using the correct security setting for the port:

- Port 587: secure: false (uses STARTTLS)

- Port 465: secure: true (uses SSL/TLS)

Development-only workaround: If you are testing locally and cannot resolve a certificate issue, you can temporarily disable certificate verification. Do not use this in production.

{
  host: 'sandbox.mailloop.io',
  port: 587,
  secure: false,
  tls: {
    rejectUnauthorized: false
  }
}

Emails Missing Content

If emails appear in the inbox but have empty or broken content:

• Send both HTML and plain text versions:

{
  text: 'Plain text version',
  html: '<p>HTML version</p>'
}

• Use UTF-8 encoding for international characters:

msg = MIMEText(text, 'plain', 'utf-8')

• Verify Content-Type headers are set correctly in your email library.

API Issues

429 Too Many Requests

You have exceeded the rate limit. Check the Retry-After response header for when to retry. See SDK Reference > Rate Limits for the current limits per endpoint.

401 Unauthorized

• Verify your API key is correct and starts with ml_live_
• Check that the key has not been revoked in the dashboard
• Ensure the Authorization header uses the Bearer scheme:

Authorization: Bearer ml_live_your_api_key_here

SDK Issues

TimeoutError on waitFor

If emails.waitFor() throws a TimeoutError:

• Increase the timeout (maximum is 60000ms):

const email = await client.emails.waitFor(sandbox.id, {
  timeout: 60000
});

• Verify the email is actually being sent to the correct sandbox (check SMTP credentials)
• Check that your filter parameters match. The subject filter uses a substring match -- "Welcome" matches "Welcome to Acme"

Module Resolution

The SDK ships with both ESM and CommonJS builds:

// ESM
import { MailloopClient } from '@mailloop/sdk';

// CommonJS
const { MailloopClient } = require('@mailloop/sdk');

Requires Node.js 18 or later.

Getting Help

If you are still experiencing issues:

1. Check the status page for service incidents
2. Contact support through the Help & Support page in the dashboard