SMTP Troubleshooting

Common issues and solutions for SMTP integration.

Authentication Failed

Symptoms: "Authentication failed" or "Invalid credentials" errors

Solutions:

• Verify motor block username and password are correct
• Check for extra spaces or hidden characters in credentials
• Ensure motor block status is "active" in the dashboard
• If using API key, verify the key hasn't been revoked
• For OAuth, ensure tokens haven't expired

Connection Timeout

Symptoms: "Connection timed out" or "Could not connect to server" errors

Solutions:

• Check firewall allows outbound connections on port 2587 or 2465
• Verify server hostname: mail.motorical.com
• Test DNS resolution: nslookup mail.motorical.com
• Try 2465 (implicit TLS) if 2587 is blocked — do not fall back to 587, which is a different service (see Authentication Methods)
• Check if your ISP blocks SMTP ports

telnet mail.motorical.com 2587
# implicit TLS alternative:
openssl s_client -connect mail.motorical.com:2465 -crlf

TLS/SSL Issues

Symptoms: "TLS negotiation failed", "SSL/TLS handshake error", or "Certificate errors"

Solutions:

• Enable STARTTLS in your SMTP client configuration
• Verify TLS version compatibility (TLS 1.2+ required)
• Update your system's CA certificate bundle
• Check system clock accuracy (must be within ±5 minutes)
• Verify certificate chain completeness

# Test TLS connection
openssl s_client -connect mail.motorical.com:2587 -starttls smtp -crlf

# Check certificate
echo | openssl s_client -connect mail.motorical.com:2587 \
  -starttls smtp 2>/dev/null | openssl x509 -noout -dates

Emails Not Delivering

Symptoms: Emails are accepted by the server but don't arrive at the destination

Solutions:

1. Check delivery logs in the Motorical dashboard
2. Verify SPF, DKIM, and DMARC DNS records are correctly configured
3. Check the Motor Block's domain health status
4. Look for bounce notifications in your Motor Block's event stream
5. Verify the recipient address is valid

Rate Limiting

Symptoms: the gateway accepts the connection and AUTH, then refuses the message with a 451 4.7.1 reply.

Motorical refuses over-quota SMTP submissions temporarily (451), never permanently (5xx) — the message is valid and will be sendable once the window resets, so a compliant sending MTA should queue and retry rather than bounce to the end user.

Reply	Meaning	Action
451 4.7.1 Rate limit exceeded (burst): <used>/<limit>. Retry in <n>s.	This Motor Block's per-minute burst ceiling	Retry after <n> seconds; spread the batch
451 4.7.1 Rate limit exceeded (hourly): …	This Motor Block's hourly ceiling	Retry after <n>; raise the block's limit or split the stream across blocks
451 4.7.1 Rate limit exceeded (daily): …	This Motor Block's daily ceiling	Retry after <n>; raise the block's limit
451 4.7.1 account-wide send limit exceeded (acct_hourly|acct_daily); upgrade your plan or wait for the window to reset: <used>/<limit>. Retry in <n>s.	The account-wide ceiling across all your Motor Blocks	Check GET /api/public/v1/account/rate-limits; upgrade the plan or wait
451 4.7.1 Sending too fast for this domain's warmup tier — …	The sending domain is still warming up and its buffer is full	Reduce volume for this domain; the tier rises automatically as reputation builds

These are the same counters the HTTP API uses — SMTP and POST /v1/send share one quota. Check headroom with GET /api/public/v1/motor-blocks/{id}/rate-limits and GET /api/public/v1/account/rate-limits. See Rate Limits & Retention.

Email Formatting Issues

Symptoms: Emails arrive with broken formatting or encoding issues

Solutions:

• Set Content-Type: text/html; charset=utf-8 for HTML emails
• Always include a plain-text alternative
• Test with multiple email clients (Gmail, Outlook, Apple Mail)
• Validate HTML with an email preview tool

Error Reference

Error Code	Meaning	Action
535	Authentication failed	Check credentials
550	Recipient rejected	Verify recipient address
421	Service temporarily unavailable	Retry with backoff
452	Too many recipients or insufficient resources on the receiving server	Reduce recipients per message; retry
451 4.7.1	Motorical send quota (see Rate Limiting above)	Queue and retry after the stated interval
554	Transaction failed	Check message content/headers

Getting Help

If you're still experiencing issues:

• Email: support@motorical.com
• Include your error details, motor block ID, and timestamps
• Check GET https://api.motorical.com/v1/status for HTTP API availability