Elastic Email API Module

Email Operations

• POST /api/emails/send

  • Send a single transactional email.
  • Body:
    • to (string, required)
    • subject (string, required)
    • body_html (string, required if body_text omitted)
    • body_text (string, required if body_html omitted)
    • from_email (string, optional)
    • from_name (string, optional)
    • reply_to (string, optional)
  • Success: 201 with { success: true, messageId, transactionId }
  • 400 on missing fields.

• POST /api/emails/bulk

  • Send bulk/campaign emails.
  • Body:
    • recipients (string[], required)
    • subject (string, required)
    • body_html/body_text (one required)
    • from_email/from_name (optional)
  • Success: 201 with { success: true, jobId, recipientCount }
  • 400 if recipients missing or content missing.

Email Verifications

• POST /api/verifications/email

  • Verify a single email address.
  • Body: { email: string } (required)
  • Success: 200 with verification result object.
  • 400 if email missing.

• GET /api/verifications/:email

  • Retrieve prior verification result for :email.
  • Note: test run indicated GET for test@example.com returned 400; behavior may require additional handling or pre-existing verification.

Suppression Lists

• POST /api/suppressions/:type

  • Add emails to suppression list.
  • Path :type must be one of: bounces, complaints, unsubscribes
  • Body: { emails: string[] } (required)
  • Success: 201 with { success: true, added: number }
  • 400 for invalid type or missing emails.

• GET /api/suppressions

  • Retrieve all suppression lists (bounces, complaints, unsubscribes).
  • Query params:
    • limit (optional, default 100)
    • offset (optional, default 0)
  • Success: 200 with object containing arrays for each suppression type.

• DELETE /api/suppressions/:type/:email

  • Remove :email from suppression list :type.
  • Path :type must be one of: bounces, complaints, unsubscribes
  • Success: 200 with { success: true, removed: email }
  • Note: test run reported a 404 for deleting bounced@example.com — check route handling and URL-encoding for emails.

Events & Statistics

• GET /api/events

  • Fetch email event logs.
  • Query params: from, to (ISO 8601), status, limit (default 100), offset (default 0)
  • Success: 200 with array of event objects.

• GET /api/statistics

  • Fetch aggregated email statistics for date range.
  • Query params: from, to (ISO 8601)
  • Success: 200 with totals and rates (sent, delivered, bounced, complaints, unsubscribed, opened, clicked, deliveryRate, openRate, clickRate)

Notes / Caveats

• ELASTIC_EMAIL_API_KEY is required for Elastic Email integration. Without it, endpoints that call Elastic Email will fail.
• Two failing tests in the provided test results suggest:
  • Verification GET may require that an address be previously verified (or different response handling).
  • Deletion from suppression lists may return 404 if the address is not present or if URL encoding causes route mismatch.
• The README and API examples use default sender values (user@example.com / Insight Vessel) when from_* is omitted — change these in your integration for production use.

If you need code-level integration guidance or examples for calling Elastic Email from within the service, provide the relevant files and I can generate snippets or suggestions aligned with the actual implementation.

This Express backend / api completed archive review with strong static results. Structure, dependency manifests, documentation, functional source, and common risk patterns were checked by the Tetrees verification pipeline; runtime phases are stated separately. Final verified scores after isolated runtime evidence: overall 8.6 and security 9.