Troubleshooting

Find solutions to common TrackPost issues. If you don’t find your answer here, contact support.

Quick Fixes

Common Issues at a Glance

API Errors

401 Unauthorized

Symptoms: API calls return 401 error

Causes:

• Invalid or missing API key
• API key expired or revoked
• Wrong environment (test key in production)

Solutions:

1. Check your API key:

   # Test key (for development)
   tp_test_abc123def456
   
   # Live key (for production)
   tp_live_abc123def456
   

2. Verify header format:

   Authorization: Bearer tp_live_your_key
   

3. Check key in dashboard:

   • Dashboard → API Keys
   • Verify key exists and is active
   • Generate new key if needed

403 Forbidden

Symptoms: API calls return 403 error

Causes:

• Insufficient permissions
• API key doesn’t have access to resource
• Domain restrictions

Solutions:

• Verify API key has correct permissions
• Check if resource belongs to your workspace
• Ensure domain is verified for sending

404 Not Found

Symptoms: API calls return 404 error

Causes:

• Resource doesn’t exist (template ID, email ID)
• Wrong endpoint URL
• Typo in ID

Solutions:

• Double-check resource IDs
• Verify endpoint URL: https://api.trackpost.de/v1/...
• List resources to find correct ID:

  curl https://api.trackpost.de/v1/templates \
    -H "Authorization: Bearer tp_live_your_key"
  

429 Rate Limit Exceeded

Symptoms: API calls return 429 error

Causes:

• Too many requests per minute
• Exceeded plan limits
• No backoff implementation

Solutions:

1. Check your limits in headers:

   X-RateLimit-Limit: 60
   X-RateLimit-Remaining: 0
   X-RateLimit-Reset: 1705323000
   

2. Implement exponential backoff:

   async function sendWithRetry(data, retries = 3) {
     for (let i = 0; i < retries; i++) {
       try {
         return await sendEmail(data);
       } catch (error) {
         if (error.status === 429) {
           const delay = Math.pow(2, i) * 1000;
           await new Promise(r => setTimeout(r, delay));
           continue;
         }
         throw error;
       }
     }
   }
   

3. Upgrade your plan for higher limits

422 Validation Error

Symptoms: API calls return 422 error with validation message

Causes:

• Invalid request parameters
• Missing required fields
• Invalid email format
• Template variables missing

Solutions:

• Check error message for specific field
• Verify all required fields are present
• Validate email format
• Ensure template variables match template requirements

Example:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid email format",
    "field": "to"
  }
}

AWS SES Issues

“AWS credentials invalid”

Symptoms: Error when sending emails, AWS connection fails

Solutions:

1. Verify credentials:

   • Check Access Key ID and Secret Access Key
   • No extra spaces or characters
   • Credentials not expired

2. Check IAM permissions:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ses:SendEmail",
           "ses:SendRawEmail",
           "ses:GetSendQuota"
         ],
         "Resource": "*"
       }
     ]
   }
   

3. Test in AWS Console:

   • SES → Email Sending → Send Test Email
   • If this fails, issue is with AWS credentials

Domain Verification “Pending”

Symptoms: Domain status stuck on “Pending” for hours

Solutions:

1. Check DNS propagation:

   dig TXT yourdomain.com
   dig TXT _amazonses.yourdomain.com
   dig TXT selector1._domainkey.yourdomain.com
   

2. Verify DNS records:

   • Exact values match what TrackPost provided
   • No extra quotes in values
   • Correct record type (TXT, not CNAME)

3. Wait longer:

   • DNS can take up to 48 hours
   • Most complete within 2-4 hours

4. Use online checker:

   • https://whatsmydns.net
   • Check globally for your records

“Sandbox Access” Error

Symptoms: Can only send to verified emails

Cause: New AWS accounts start in sandbox mode

Solution:

1. Request production access:

   • AWS Console → SES → Account dashboard
   • Click “Request production access”
   • Fill out the form explaining your use case

2. While waiting:

   • Verify recipient email addresses in AWS
   • Continue testing with verified addresses
   • Approval usually takes 24 hours

Emails Going to Spam

Symptoms: Recipients report emails in spam folder

Checklist:

1. Authentication:

   • SPF record: v=spf1 include:amazonses.com ~all
   • DKIM: Enabled in TrackPost
   • DMARC: _dmarc TXT record set

2. Content:

   • Avoid spammy words (“FREE!!!”, “Act now!!!”)
   • Balanced text-to-image ratio
   • Valid HTML structure

3. Reputation:

   • Check AWS SES reputation dashboard
   • Low bounce rate (< 2%)
   • Low complaint rate (< 0.1%)

4. Test:

   • Use mail-tester.com
   • Check spam score

CLI Issues

“command not found: trackpost”

Symptoms: After installing CLI, command not found

Solutions:

1. Install globally:

   npm install -g @trackpost/cli
   

2. Check npm global path:

   npm bin -g
   # Add to PATH if needed
   

3. Use npx:

   npx @trackpost/cli --version
   

“Authentication failed”

Symptoms: CLI can’t authenticate

Solutions:

• Run trackpost auth login again
• Check API key is correct
• Verify key is for correct environment
• Try trackpost auth logout then login again

Template Issues

“Template not found”

Symptoms: Error when using template_id

Solutions:

• Verify template ID exists: trackpost templates list
• Check for typos in template_id
• Ensure template is in correct workspace

“Invalid variables”

Symptoms: Template validation fails

Solutions:

• Preview template with variables:

  trackpost templates render template_id \
    --variables '{"var":"value"}'
  

• Check all required variables are provided
• Verify variable names match template

“Liquid syntax error”

Symptoms: Template won’t save or render

Common errors:

{% if condition %}     {# Missing endif #}

{% for item in items   {# Missing closing brace #}

{{ variable | unknown_filter }}  {# Invalid filter #}

Solutions:

• Ensure all tags are properly closed
• Use valid Liquid filters only
• Check template in preview mode

Webhook Issues

Webhooks not received

Symptoms: No webhook calls coming to your endpoint

Checklist:

1. Verify webhook is active:

   • Dashboard → Webhooks
   • Status should be “Active”

2. Check URL is correct:

   • Must be HTTPS (not HTTP)
   • Publicly accessible
   • Returns 200 status

3. Test endpoint:

   curl -X POST https://your-endpoint.com/webhook \
     -d '{"test": true}'
   

4. Check server logs:

   • Look for incoming requests
   • Check for errors processing webhooks

“Invalid signature”

Symptoms: Signature verification fails

Solutions:

• Ensure you’re using the correct webhook secret
• Verify signature calculation:

  const signature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  

• Check for extra whitespace in payload

Duplicate webhooks

Symptoms: Same event received multiple times

Cause: TrackPost retries failed webhooks

Solution: Implement idempotency:

// Check if already processed
const processed = await db.webhooks.findOne({ 
  event_id: event.id 
});

if (processed) {
  return res.status(200).send('Already processed');
}

// Process and record
await processEvent(event);
await db.webhooks.insert({ 
  event_id: event.id,
  processed_at: new Date()
});

Email Delivery Issues

High Bounce Rate

Symptoms: > 5% of emails bouncing

Solutions:

1. Clean your list:

   • Remove hard bounces immediately
   • Verify emails before adding
   • Use double opt-in

2. Check for typos:

   • Common: gmial.com, yahooo.com
   • Validate email format

3. Monitor soft bounces:

   • Temporary issues (full mailbox, server down)
   • Retry with exponential backoff

High Complaint Rate

Symptoms: > 0.1% of emails marked as spam

Solutions:

1. Verify opt-in:

   • Only send to users who opted in
   • Use double opt-in
   • Honor unsubscribe immediately

2. Improve content:

   • Clear subject lines
   • Recognizable sender name
   • Easy unsubscribe

3. Review frequency:

   • Don’t send too often
   • Segment by engagement
   • Sunset inactive users

Emails Not Sending

Symptoms: API returns success but no emails sent

Checklist:

1. Check dashboard:

   • Do emails appear in Emails list?
   • What status do they show?

2. Check AWS:

   • AWS credentials configured?
   • SES sending quota not exceeded?
   • Account not paused?

3. Check suppression list:

   • Email might be suppressed
   • Check Dashboard → Suppressions

Frequently Asked Questions

General

Technical

async function sendWithRetry(data, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await send(data);
    } catch (error) {
      if (error.status === 429) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

Billing

Getting Help

Support Channels

• Documentation: You’re here! Check all guides first.
• GitHub Issues: https://github.com/anomalyco/trackpost/issues
• Email Support: [email protected]
• Contact Form: Contact us

Information to Provide

When contacting support, include:

1. Account details:

   • Workspace ID (from dashboard)
   • API key type (test/live) - don’t share the actual key!

2. Error information:

   • Exact error message
   • Error code (if any)
   • Request ID (from error response)

3. What you were doing:

   • API endpoint used
   • Code snippet (remove sensitive data)
   • Timestamp of error

4. What you’ve tried:

   • Steps already attempted
   • Documentation sections checked

Response Times

Still stuck? Contact Support with the information above and we’ll help you out!