Transactional email troubleshooting

This article covers the most common issues with Flexmail transactional email — authentication errors, deliverability problems, and API or SMTP failures — and what to do about each.

Authentication and setup errors

API returns a 401 Unauthorized error

Your account ID or personal access token is wrong. Check both carefully:

• The username is your numeric account ID, not your email address.
• The password is a personal access token created in Settings > API > Personal access tokens, not your Flexmail login password.
• Make sure the token was copied in full with no trailing spaces or line breaks.
• If in doubt, create a new token and try again.

SMTP connection fails or times out

Check the following:

• You are using host submission.flexmail.eu, port 587, with STARTTLS.
• Your server or hosting environment allows outbound connections on port 587. Some shared hosting providers block this port — contact your host to confirm.
• Your SMTP credentials are the username and password provided by Flexmail when they activated your SMTP access. These are separate from your account ID and personal access token, which are used for the HTTP API only.
• Your sender address is verified in Flexmail.

Sender address not verified

If you try to send from an address that is not verified in Flexmail, the send will be rejected. Go to Settings > Add or remove senders, add the address, and click the verification link in the email Flexmail sends.

Deliverability problems

Emails are going to spam

Spam placement on transactional email is almost always caused by one of three things:

• Email authentication is not configured or is incorrect. Check that SPF, DKIM, and DMARC records are in place for your sending domain. Even one missing or misconfigured record can cause spam placement. Configuration instructions are in the API documentation at email-api.flexmail.eu/documentation under Email authentication.
• Sender reputation is low. If your domain or IP has a history of spam complaints or high bounce rates — from any sending platform, not just Flexmail — inbox providers may route your email to spam. See "Understanding sender reputation" for how to assess and improve reputation.
• Content triggers spam filters. Certain subject line patterns, excessive links, or image-heavy emails with little text can trigger spam filters. Test your transactional emails with a tool like Mail-Tester (mail-tester.com) to identify content-level issues.

Emails are not arriving at all

If the API returns a success response but the email does not arrive:

• Check your webhook events (if configured) — a bounce event shortly after send indicates a delivery failure.
• Verify that the recipient address exists and is spelled correctly.
• Ask the recipient to check their spam folder.
• Check whether the recipient's domain has a strict DMARC policy — without correctly configured DKIM, your emails may be silently rejected.
• Some corporate email systems reject email from new or low-reputation senders. Try sending to a personal Gmail or Outlook address to rule out recipient-side filtering.

High bounce rate

A high bounce rate on transactional email usually means you are sending to addresses that do not exist or are no longer active. Check your address collection process:

• Are you validating email address format at the point of entry?
• Are you sending a confirmation or verification email before trusting a new address?
• Are you removing hard-bounced addresses from your system promptly?

API and integration errors

API returns a 422 or 400 error

These errors indicate a problem with your request — a missing required field, an invalid parameter value, or a malformed request body. Check the error message in the response body for details. The API documentation at email-api.flexmail.eu/documentation lists all required and optional parameters for each endpoint.

API returns a 429 Too Many Requests error

You have hit a rate limit. The API documentation specifies the rate limits for your subscription tier. Add retry logic with exponential backoff to your integration to handle this gracefully.

Template variables are not being replaced

If placeholder text appears literally in the delivered email:

• Check that you are passing the variable values correctly in the API request. See the Templates section of the API documentation for the exact parameter structure.
• Check that the placeholder syntax in your template matches exactly what the API expects.
• Make sure you are referencing the correct template ID in your API call.

Webhooks are not arriving

If your webhook endpoint is not receiving events:

• Confirm your endpoint is publicly accessible over HTTPS.
• Check that your endpoint returns a 2xx response quickly — a slow or non-responding endpoint will cause Flexmail to consider the delivery failed.
• Check your server logs for incoming POST requests to rule out a routing or firewall issue.
• Verify your webhook endpoint URL is registered correctly in the API.

Getting help

If you have worked through the above and the issue persists, contact the Flexmail support team at support@flexmail.eu. Include the following in your message to speed up diagnosis:

• The message ID of a failing send (from the API response or your logs).
• The recipient email address you tested with.
• The error message or response body from the API, if applicable.
• The result of an email authentication check tool such as MXToolbox or Mail-Tester.

Next steps

• See "Getting started with the transactional API" for the correct setup sequence.
• See "Understanding sender reputation" for how to assess and protect your sending reputation.
• Review the API documentation at email-api.flexmail.eu/documentation for error codes and rate limit details.