Email infrastructure API with logs

Here’s a solid way to think about an email infrastructure API with logs.

Core concept

An email infrastructure API typically lets you:

• send emails
• manage templates
• track delivery status
• view logs for each message
• handle webhooks for events like delivered, opened, bounced, complained

Main API capabilities

1. Send email

POST /emails/send

Example request:

{
  "to": "user@example.com",
  "from": "no-reply@yourdomain.com",
  "subject": "Welcome!",
  "template_id": "tmpl_123",
  "variables": {
    "name": "Alice"
  }
}

Example response:

{
  "message_id": "msg_abc123",
  "status": "queued"
}

---

2. Get email status

GET /emails/{message_id}

Example response:

{
  "message_id": "msg_abc123",
  "status": "delivered",
  "sent_at": "2026-10-27T12:00:00Z",
  "delivered_at": "2026-10-27T12:00:05Z"
}

---

3. List logs

GET /logs/emails

Useful filters:

• status=failed
• recipient=user@example.com
• from_date=...
• to_date=...
• provider=ses|sendgrid|mailgun

Example response:

{
  "items": [
    {
      "id": "log_1",
      "message_id": "msg_abc123",
      "recipient": "user@example.com",
      "status": "delivered",
      "provider": "ses",
      "timestamp": "2026-10-27T12:00:05Z"
    }
  ]
}

---

4. View detailed log entry

GET /logs/emails/{log_id}

Could include:

• provider response
• SMTP response code
• error details
• retry count
• webhook history

---

5. Webhooks for events

POST /webhooks/email-events

Event types:

• queued
• sent
• delivered
• opened
• clicked
• bounced
• complained
• failed

Example webhook payload:

{
  "event": "delivered",
  "message_id": "msg_abc123",
  "recipient": "user@example.com",
  "timestamp": "2026-10-27T12:00:05Z"
}

---

Recommended log fields

For each email log, store:

• id
• message_id
• tenant_id / account_id
• recipient
• sender
• subject
• template_id
• provider
• status
• error_code
• error_message
• attempt_number
• created_at
• updated_at
• provider_message_id
• metadata

---

Best practices

• Store logs separately from message queue records
• Use a unique message_id and provider_message_id
• Keep raw provider payloads for debugging
• Add pagination and filtering to log endpoints
• Redact sensitive data in logs where needed
• Support retries with attempt history
• Index logs by message_id, recipient, status, and created_at

---

Suggested minimal API design

Send

POST /v1/emails

Status

GET /v1/emails/{id}

Logs

GET /v1/email-logs

Log detail

GET /v1/email-logs/{id}

Webhook receiver

POST /v1/webhooks/email-events

---

If you want, I can also provide:

1. a full OpenAPI spec
2. a database schema
3. a Node.js / Python implementation
4. a logging architecture for high-volume email systems