Common Issues

API Errors

”Template not found”

Cause: The template ID doesn’t exist or doesn’t belong to your account.

Solutions:

1. Verify the template ID is correct
2. Check you’re using the right API key (same account as template)
3. Ensure template wasn’t deleted

”Template not found in flow graph”

Cause: The template exists but isn’t added to the project’s flow.

Solutions:

1. Open the project in the editor
2. Add the template to the flow canvas
3. Connect it to an output node
4. Save the project

”Provider configuration not found”

Cause: The provider referenced in the flow doesn’t exist.

Solutions:

1. Check the provider wasn’t deleted
2. Add or reconfigure the provider in Settings
3. Update the flow to use an existing provider

”_to is required for provider output”

Cause: You’re using a provider output but didn’t specify a recipient.

Solutions:

1. Add _to to your API request
2. Or switch to callback output if you don’t want to send

{
  "templateId": "...",
  "variables": {...},
  "_to": "recipient@example.com"
}

”Invalid API key”

Cause: The API key is wrong, revoked, or malformed.

Solutions:

1. Check the key in Settings > API Keys
2. Regenerate if compromised
3. Verify the Authorization header format: Bearer your_key

Template Issues

Variables not being replaced

Symptoms: Seeing {{variableName}} in rendered output.

Causes & Solutions:

1. Spelling mismatch - Variable names are case-sensitive

   • Template: {{firstName}}
   • API: { "firstname": "..." } ❌
   • API: { "firstName": "..." } ✓

2. Wrong delimiter - Must be double curly braces

   • {name} ❌
   • {{name}} ✓

3. Variable not in request - Add it or use a default

   • {{name|default}} uses “default” if not provided

Subject line not working

Cause: Subject priority confusion.

Priority order:

1. _subject from API request (highest)
2. Subject set in template
3. Template name (fallback)

Solution: Set subject in template or pass _subject in API.

Images not displaying

Causes:

1. Image URL is broken or inaccessible
2. URL is HTTP (some clients block)
3. Image file is too large

Solutions:

1. Verify URL loads in browser
2. Use HTTPS URLs
3. Optimize images (< 1MB recommended)
4. Use reliable image hosting (CDN)

Provider Issues

”Sender not verified”

Cause: Email provider requires sender verification.

Solutions by provider:

• Resend: Verify domain in dashboard
• SendGrid: Complete sender authentication
• Postmark: Add sender signature
• AWS SES: Verify email or domain

”Rate limit exceeded”

Cause: Sending too fast for your plan.

Solutions:

1. Implement rate limiting in your code
2. Upgrade provider plan
3. Add delays between sends
4. Queue emails for gradual sending

”Authentication failed”

Cause: Provider credentials are wrong.

Solutions:

1. Regenerate API key at provider
2. Update credentials in mailshit Settings
3. Check for typos or extra whitespace

Flow Issues

No output from flow

Cause: Template isn’t connected to an output node.

Solution:

1. Open project flow editor
2. Add Provider or Callback output node
3. Connect template to output
4. Save

Verification keeps failing

Causes:

1. Invalid email format in _to
2. Missing required fields
3. Regex pattern mismatch

Solutions:

1. Check the error message for which field failed
2. Validate inputs before calling API
3. Test with known-good values

Editor Issues

Can’t save template

Causes:

1. Network connectivity issues
2. Session expired
3. Browser extension interference

Solutions:

1. Check internet connection
2. Refresh page and try again
3. Disable ad blockers temporarily
4. Try incognito mode

Preview not updating

Cause: Browser caching or state issue.

Solutions:

1. Hard refresh: Cmd/Ctrl + Shift + R
2. Clear browser cache
3. Close and reopen editor

Getting Help

If these solutions don’t help:

1. Check the full documentation
2. Review error messages carefully
3. Contact support at contact