Errors & Retries

{
  "error_code": "validation_error",
  "message": "The given data was invalid.",
  "errors": {
    "to": ["The to field is required."],
    "subject": ["The subject must not exceed 998 characters."]
  }
}

try {
  await lettr.emails.send(emailData);
} catch (error) {
  if (error.status === 422) {
    console.log('Validation errors:', error.errors);

    if (error.errors.to) {
      console.log('Invalid recipients:', error.errors.to);
    }
    if (error.errors.from) {
      console.log('Invalid sender:', error.errors.from);
    }
  }
}

try {
  await lettr.emails.send({
    from: 'you@unverified-domain.com',
    to: ['recipient@example.com'],
    subject: 'Hello',
    html: '<p>Hello!</p>'
  });
} catch (error) {
  if (error.error_code === 'invalid_domain') {
    console.log('Domain not verified. Please verify your domain first.');
  }
  if (error.error_code === 'unconfigured_domain') {
    console.log('Domain DNS records not configured correctly.');
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Retry-After carries seconds or an HTTP date. Without it, back off exponentially with full jitter.
function retryDelay(attempt, retryAfter) {
  if (retryAfter) {
    const seconds = Number(retryAfter);
    const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(retryAfter) - Date.now();
    if (ms > 0) return ms;
  }
  const capMs = Math.min(30_000, 1_000 * 2 ** attempt);
  return Math.random() * capMs;
}

async function sendEmailWithRetry(payload, idempotencyKey, { maxAttempts = 3 } = {}) {
  const body = JSON.stringify(payload);
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    let response = null;
    try {
      response = await fetch('https://app.lettr.com/api/emails', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.LETTR_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body,
        signal: AbortSignal.timeout(30_000),
      });
    } catch (error) {
      // Network failure or timeout. The same key makes the retry safe either way.
      lastError = error;
    }

    let retryAfter = null;
    if (response) {
      // Gateway errors can carry a non-JSON body. Decide from the status either way.
      const data = (await response.json().catch(() => null)) ?? {};

      if (response.ok && data.data?.request_id) {
        return data;
      }

      if (response.ok) {
        // A 2xx with a truncated or malformed body. The same key replays the original result.
        lastError = new Error('Success response could not be parsed');
      } else {
        const retryable =
          response.status >= 500 ||
          response.status === 429 ||
          data.error_code === 'idempotency_in_progress';

        if (!retryable) {
          throw Object.assign(new Error(data.message || response.statusText), {
            status: response.status,
            error_code: data.error_code,
            errors: data.errors,
          });
        }

        lastError = Object.assign(new Error(data.message || response.statusText), {
          status: response.status,
          error_code: data.error_code,
          retryAfter: response.headers.get('Retry-After'),
        });
        retryAfter = response.headers.get('Retry-After');
      }
    }

    if (attempt < maxAttempts) {
      await sleep(retryDelay(attempt, retryAfter));
    }
  }

  throw lastError;
}

async function sendEmail(emailData, idempotencyKey) {
  try {
    const response = await sendEmailWithRetry(emailData, idempotencyKey);
    return { success: true, data: response.data };
  } catch (error) {
    console.error('Email send failed:', {
      error_code: error.error_code,
      message: error.message,
      to: emailData.to,
      timestamp: new Date().toISOString()
    });

    switch (error.error_code) {
      case 'validation_error':
        return { success: false, error: 'Invalid email data', details: error.errors };

      case 'invalid_domain':
        return { success: false, error: 'Sender domain not verified' };

      case 'idempotency_key_conflict':
        return { success: false, error: 'Idempotency key reused with a different payload' };

      case 'rate_limit_exceeded':
        return { success: false, error: 'Rate limit exceeded', retryAfter: error.retryAfter };

      default:
        return { success: false, error: 'Failed to send email' };
    }
  }
}

class EmailCircuitBreaker {
  constructor(threshold = 5, resetTimeout = 60000) {
    this.failures = 0;
    this.threshold = threshold;
    this.resetTimeout = resetTimeout;
    this.state = 'closed';
    this.lastFailure = null;
  }

  async send(emailData) {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailure > this.resetTimeout) {
        this.state = 'half-open';
      } else {
        throw new Error('Circuit breaker is open');
      }
    }

    try {
      const result = await lettr.emails.send(emailData);
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  onSuccess() {
    this.failures = 0;
    this.state = 'closed';
  }

  onFailure() {
    this.failures++;
    this.lastFailure = Date.now();
    if (this.failures >= this.threshold) {
      this.state = 'open';
    }
  }
}

app.post('/webhooks/lettr', (req, res) => {
  const event = req.body;

  if (event.type === 'generation.generation_failure' || event.type === 'message.bounce') {
    alertTeam({
      type: event.type,
      email_id: event.data.email_id,
      recipient: event.data.to,
      error: event.data.error_message
    });
  }

  res.sendStatus(200);
});