Email Logs Guide

The Email Logs API provides access to detailed delivery status and activity information for all emails sent through EDITH.

Overview

Email logs allow you to:

Track email delivery status
View open and click activity
Debug delivery issues
Generate reports and analytics
Monitor campaign performance

Get Email Logs

Endpoint

GET /v1/email/logs

Authentication

Requires Bearer token authentication.

Query Parameters

All parameters are optional and can be combined for precise filtering:

Parameter	Type	Description
`email`	string	Filter by recipient email address (exact match)
`recipientDomain`	string	Filter by recipient's email domain (exact match)
`refId`	string	Filter by email reference ID (returned when sending)
`status`	string	Filter by delivery status
`fromAddress`	string	Filter by sender email address (exact match)
`subject`	string	Filter by email subject (exact match)
`campaignId`	string	Filter by campaign ID
`recipientType`	string	Filter by recipient type: `"to"`, `"cc"`, `"bcc"`
`failedReason`	string	Filter by failure reason
`startCreatedAt`	string	Start date for creation date filter (RFC3339 format)
`endCreatedAt`	string	End date for creation date filter (RFC3339 format)
`startDeliveredDate`	string	Start date for delivery date filter (RFC3339 format)
`endDeliveredDate`	string	End date for delivery date filter (RFC3339 format)
`pageSize`	integer	Number of results per page (default: 20, max: 50)
`pageToken`	string	Token for pagination

Email Status Values

Status	Description
`queued`	Email is queued for sending
`sent`	Email sent to the mail server
`delivered`	Email successfully delivered to recipient's inbox
`opened`	Recipient opened the email (if tracking enabled)
`clicked`	Recipient clicked a link (if tracking enabled)
`bounced`	Email bounced (soft or hard)
`failed`	Email failed to send
`spam`	Email marked as spam
`unsubscribed`	Recipient unsubscribed

Example Requests

Get All Logs (Paginated)

curl -X GET "https://api.edith.example.com/v1/email/logs?pageSize=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter by Recipient Email

curl -X GET "https://api.edith.example.com/v1/email/logs?email=customer@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter by Status

curl -X GET "https://api.edith.example.com/v1/email/logs?status=bounced" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter by Campaign

curl -X GET "https://api.edith.example.com/v1/email/logs?campaignId=welcome-series-2024" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter by Date Range

curl -X GET "https://api.edith.example.com/v1/email/logs?startCreatedAt=2024-01-01T00:00:00Z&endCreatedAt=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter by Reference ID

curl -X GET "https://api.edith.example.com/v1/email/logs?refId=01JC3BBW8S9YGX2VNKG5MD7BTA" \
  -H "Authorization: Bearer YOUR_TOKEN"

Combine Multiple Filters

curl -X GET "https://api.edith.example.com/v1/email/logs?campaignId=promo-jan&status=delivered&startCreatedAt=2024-01-15T00:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

{
  "success": true,
  "emailLogs": [
    {
      "refId": "01JC3BBW8S9YGX2VNKG5MD7BTA",
      "accountId": 12345,
      "tenantId": 67890,
      "fromAddress": "notifications@mail.yourcompany.com",
      "recipientAddress": "customer@example.com",
      "recipientDomain": "example.com",
      "recipientType": "to",
      "subject": "Your Order Confirmation",
      "status": "delivered",
      "priority": "normal",
      "campaignId": "order-confirmation",
      "opened": true,
      "clicked": true,
      "failedReason": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "deliveredDate": "2024-01-15T10:30:05Z",
      "updatedAt": "2024-01-15T11:45:00Z",
      "track": {
        "opens": [
          {
            "timestamp": "2024-01-15T11:00:00Z",
            "userAgent": "Mozilla/5.0...",
            "ip": "192.168.1.1"
          }
        ],
        "clicks": [
          {
            "timestamp": "2024-01-15T11:05:00Z",
            "url": "https://yourcompany.com/orders/12345",
            "userAgent": "Mozilla/5.0...",
            "ip": "192.168.1.1"
          }
        ]
      }
    }
  ],
  "nextPageToken": "eyJJZCI6IjAxSkM0...",
  "totalCount": 150
}

Response Fields Explained

Email Log Entry

Field	Type	Description
`refId`	string	Unique reference ID for this email (returned when sending)
`accountId`	integer	Your account identifier
`tenantId`	integer	Tenant/organization identifier
`fromAddress`	string	Sender email address
`recipientAddress`	string	Recipient email address
`recipientDomain`	string	Domain portion of recipient email
`recipientType`	string	How recipient was addressed: `"to"`, `"cc"`, `"bcc"`
`subject`	string	Email subject line
`status`	string	Current delivery status
`priority`	string	Email priority: `"normal"` or `"high"`
`campaignId`	string	Campaign identifier (if provided when sending)
`opened`	boolean	Whether email has been opened (if tracking enabled)
`clicked`	boolean	Whether any links were clicked (if tracking enabled)
`failedReason`	string	Reason for failure (if status is failed/bounced)
`createdAt`	string	When the email was created (RFC3339)
`deliveredDate`	string	When the email was delivered (RFC3339)
`updatedAt`	string	Last update timestamp (RFC3339)
`track`	object	Detailed tracking events (opens, clicks)

Track Object

Field	Type	Description
`opens`	array	List of open events with timestamp, userAgent, and IP
`clicks`	array	List of click events with timestamp, URL, userAgent, and IP

Pagination

The API uses cursor-based pagination for efficient handling of large result sets.

Initial Request

curl -X GET "https://api.edith.example.com/v1/email/logs?pageSize=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Use the nextPageToken from the previous response:

curl -X GET "https://api.edith.example.com/v1/email/logs?pageSize=50&pageToken=eyJJZCI6IjAxSkM0..." \
  -H "Authorization: Bearer YOUR_TOKEN"

Pagination Tips

Maximum pageSize is 50
nextPageToken is null when no more results
Tokens are short-lived; don't cache them for extended periods
Total count may be approximate for very large datasets

Use Cases

1. Track Specific Email Delivery

# Using the ref_id from send response
curl -X GET "https://api.edith.example.com/v1/email/logs?refId=01JC3BBW8S9YGX2VNKG5MD7BTA" \
  -H "Authorization: Bearer YOUR_TOKEN"

2. Find Bounced Emails

curl -X GET "https://api.edith.example.com/v1/email/logs?status=bounced&pageSize=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Campaign Performance

curl -X GET "https://api.edith.example.com/v1/email/logs?campaignId=black-friday-2024" \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Recipient History

curl -X GET "https://api.edith.example.com/v1/email/logs?email=important-customer@company.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

5. Domain-Wide Issues

# Check if emails to a specific domain are failing
curl -X GET "https://api.edith.example.com/v1/email/logs?recipientDomain=problematic-domain.com&status=failed" \
  -H "Authorization: Bearer YOUR_TOKEN"

6. Recent Failures

curl -X GET "https://api.edith.example.com/v1/email/logs?status=failed&startCreatedAt=2024-01-15T00:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

1. Use Specific Filters

Narrow down results to improve performance:

# Good: Specific filters
?campaignId=promo-jan&status=delivered&startCreatedAt=2024-01-01T00:00:00Z

# Avoid: No filters on large datasets
?pageSize=50

2. Store Reference IDs

When sending emails, store the ref_id for easy lookup:

const response = await sendEmail(payload);
await database.saveEmailRecord({
  orderId: order.id,
  emailRefId: response.ref_id,
  sentAt: new Date()
});

3. Use Campaign IDs Consistently

Tag emails with meaningful campaign IDs:

const payload = {
  // ... email content
  campaign_id: `${emailType}-${year}-${quarter}`
  // e.g., "welcome-2024-q1", "invoice-2024-q1"
};

4. Handle Pagination Properly

async function getAllBouncedEmails() {
  const allLogs = [];
  let pageToken = null;
  
  do {
    const params = new URLSearchParams({
      status: 'bounced',
      pageSize: '50'
    });
    if (pageToken) params.set('pageToken', pageToken);
    
    const response = await fetch(
      `https://api.edith.example.com/v1/email/logs?${params}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    const data = await response.json();
    
    allLogs.push(...data.emailLogs);
    pageToken = data.nextPageToken;
  } while (pageToken);
  
  return allLogs;
}

5. Monitor Failed Emails

Set up regular checks for failures:

// Daily bounce report
const yesterday = new Date(Date.now() - 86400000).toISOString();
const bouncedEmails = await getEmailLogs({
  status: 'bounced',
  startCreatedAt: yesterday
});

if (bouncedEmails.length > threshold) {
  alertOps('High bounce rate detected');
}

Common Errors

Error	Cause	Solution
`Bad Request`	Invalid query parameters	Check parameter format
`Invalid date format`	Wrong date format	Use RFC3339 (e.g., `2024-01-15T10:30:00Z`)
`Page token expired`	Token too old	Start pagination from beginning
`Unauthorized`	Invalid token	Refresh authentication token

Send Email - Get ref_id for tracking
Webhooks - Real-time event notifications
Subscribe/Unsubscribe - Manage recipient preferences

Email Logs Guide

Overview​

Get Email Logs​

Endpoint​

Authentication​

Query Parameters​

Email Status Values​

Example Requests​

Get All Logs (Paginated)​

Filter by Recipient Email​

Filter by Status​

Filter by Campaign​

Filter by Date Range​

Filter by Reference ID​

Combine Multiple Filters​

Response Format​

Response Fields Explained​

Email Log Entry​

Track Object​

Pagination​

Initial Request​

Next Page​

Pagination Tips​

Use Cases​

1. Track Specific Email Delivery​

2. Find Bounced Emails​

3. Campaign Performance​

4. Recipient History​

5. Domain-Wide Issues​

6. Recent Failures​

Best Practices​

1. Use Specific Filters​

2. Store Reference IDs​

3. Use Campaign IDs Consistently​

4. Handle Pagination Properly​

5. Monitor Failed Emails​

Common Errors​

Related Endpoints​