Debugging | Docs | mailshit

Debugging Approach

When something goes wrong, follow this process:

Identify the symptom - What’s happening?
Check the response - What did the API return?
Isolate the problem - Where does it break?
Test the fix - Verify the solution works

API Response Analysis

Success Response

{
  "success": true,
  "type": "sent",
  "messageId": "msg_abc123"
}

Everything worked. Store messageId for tracking.

Validation Failed

{
  "success": false,
  "type": "validation_failed",
  "error": "Invalid email address",
  "field": "_to"
}

The field tells you exactly what to fix.

Send Failed

{
  "success": false,
  "type": "send_failed",
  "error": "Recipient email is not verified"
}

Check your provider dashboard for more details.

Flow Error

{
  "success": false,
  "type": "flow_error",
  "error": "Template not found in flow graph"
}

Configuration issue in mailshit—check your flow.

Using Callback Output for Debugging

Temporarily switch to callback output to debug rendering:

Change provider output → callback output in flow
Call the API
Inspect the returned HTML
Verify variables are replaced correctly
Switch back to provider output when fixed

{
  "success": true,
  "type": "callback",
  "html": "<!DOCTYPE html>...",
  "text": "Plain text...",
  "subject": "Your subject"
}

Render-Only Debugging

Use /render to test template rendering without sending:

curl -X POST https://api.mailsh.it/v1/render \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_abc123",
    "variables": {
      "firstName": "Test"
    }
  }'

Check the HTML output for:

Variable replacement
Correct structure
Subject line

Common Debug Scenarios

Email Not Arriving

Check API response - Did it say success?
Check spam folder - Common for new senders
Check provider dashboard - Delivery status
Verify recipient - Correct email address?
Check provider limits - Quota exceeded?

Wrong Content in Email

Check template - Correct template ID?
Check variables - All provided correctly?
Test with /render - See raw output
Check for typos - Variable names are case-sensitive

Verification Failing

Read the error - Which field failed?
Check the value - Is it valid?
Test verification - Use /verify endpoint
Check flow config - Verification settings correct?

Logging Recommendations

Log these for debugging:

// Before sending
console.log('Sending email:', {
  templateId,
  to: recipient,
  variables: Object.keys(variables),
})

// After response
console.log('Email result:', {
  success: result.success,
  type: result.type,
  messageId: result.messageId,
  error: result.error,
})

Don’t log:

Full email content (privacy)
API keys
Sensitive variable values

Provider-Side Debugging

Resend

Activity feed shows all sends
View email content
See delivery status

SendGrid

Activity tab for email status
Event webhooks for real-time updates
Suppression lists for bounces

Postmark

Activity stream
Message details
Bounce tracking

AWS SES

CloudWatch metrics
SNS notifications for bounces
Sending statistics

Testing in Development

Local Testing

Use callback output to test without sending:

// In development, always use callback
const endpoint = isDev
  ? '/v1/render'
  : '/v1/execute'

Test Recipients

Send test emails to:

Your own email
Email testing services (Mailinator, etc.)
Team distribution list

Test Variables

Create a test payload with all variables:

const testVariables = {
  firstName: 'Test',
  lastName: 'User',
  orderNumber: 'TEST-12345',
  // ... all variables
}

Checklist

When debugging, check:

Getting Help

If you’re stuck:

Gather information:
- API request (without secrets)
- API response
- Template ID
- Error message
Check documentation for the specific error
Contact support with the gathered information