Skip to content

Campaign Reports

Track campaign performance with comprehensive reporting and analytics.

Features:

  • Overview statistics (sends, opens, clicks, bounces, rates)
  • Contact-level drill-down (who opened, who clicked)
  • Timeline charts (hourly/daily breakdowns)
  • Link click analysis
  • Scanner vs human filtering for accurate metrics

Supported Campaign Types:

✅ Send to Segment (/api/v1/send-segment)

  • Campaign ID = job_id returned from the API
  • Sends to contacts matching segment filters
  • Full campaign analytics available

✅ Bulk Newsletter (/api/v1/bulk-send)

  • Campaign ID = campaign_id or bulk_session_id (UUID) returned from the API
  • Both fields contain the same UUID value for campaign tracking
  • Mail merge with personalized variables
  • Full campaign analytics available

❌ Batch Send (/api/v1/batch)

  • No unified campaign tracking (individual emails)
  • Use Statistics API (/api/v1/stats) for aggregate analytics
  • Use Events API (/api/v1/events) for individual email logs

Example Workflows:

// Send to Segment Campaign
const { job_id } = await sendSegment({ segment_id, subject, html, from });
const report = await fetch(`/api/v1/campaigns/${job_id}/report?filter=human_only`);

// Bulk Newsletter Campaign
const { campaign_id } = await bulkSend({ recipients, subject, html, from });
// Note: bulk_session_id also available (same value as campaign_id)
const report = await fetch(`/api/v1/campaigns/${campaign_id}/report?filter=human_only`);

// View contacts who opened
const openers = await fetch(`/api/v1/campaigns/${campaignId}/contacts/opened`);

Scanner Filtering: All endpoints support filter query parameter:

  • all - Include all activity (default)
  • human_only - Exclude scanner/bot activity (recommended for metrics)
  • scanner_only - Only scanner/bot activity

Use Cases:

  • Track newsletter performance
  • Measure campaign ROI
  • Identify engaged subscribers
  • Optimize send times with timeline data
  • Analyze link popularity
Operations

Get campaign overview report

Request

Get comprehensive campaign statistics including sends, opens, clicks, bounces, and calculated rates.

Supported Campaign Types:

  • Send to Segment: Use the job_id returned from /api/v1/send-segment
  • Bulk Newsletter: Use the campaign_id (or bulk_session_id) UUID returned from /api/v1/bulk-send
  • Batch Send: Not supported (use /api/v1/stats or /api/v1/events instead)

Important: For bulk-send campaigns, use the UUID directly (e.g., f1e2d3c4-b5a6-7890-cdef-123456789abc), NOT a prefixed string.

Metrics Included:

  • Total sent, delivered, bounced (hard/soft breakdown)
  • Unique opens, total opens, open rate
  • Unique clicks, total clicks, click rate, click-to-open rate
  • Complaints and unsubscribes
  • Campaign date range (first/last sent)

Scanner Filtering: Use the filter parameter to exclude bot/scanner activity for accurate engagement metrics.

Security
ApiKeyAuth
Path
campaignIdstring, (uuid)required

Campaign ID - either:

  • job_id from /api/v1/send-segment response
  • bulk_session_id from /api/v1/bulk-send response
Example:f1e2d3c4-b5a6-7890-cdef-123456789abc
Query
filterstring

Filter opens/clicks by scanner activity:

  • all - Include all activity (default)
  • human_only - Exclude scanner/bot opens and clicks (recommended)
  • scanner_only - Only scanner/bot activity
Default:"all"
Enum:"all""human_only""scanner_only"
curl -i -X GET \
  'https://api.mailerlogic.net/api/v1/campaigns/f1e2d3c4-b5a6-7890-cdef-123456789abc/report?filter=all' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Campaign report retrieved successfully

Bodyapplication/json
successboolean
Example:true
campaign_idstring, (uuid)
Example:"f1e2d3c4-b5a6-7890-cdef-123456789abc"
overviewobject
filter_appliedstring

Filter applied to the data

Example:"human_only"
status_definitionsobject

Explanation of email status values

Response
{
  "success": true,
  "campaign_id": "f1e2d3c4-b5a6-7890-cdef-123456789abc",
  "overview": {
    "total_sent": 1085,
    "delivered": 1072,
    "bounced": 8,
    "failed": 3,
    "deferred": 2,
    "hard_bounce": 8,
    "soft_bounce": 5,
    "unique_opens": 363,
    "total_opens": 526,
    "unique_clicks": 48,
    "total_clicks": 59,
    "complaints": 2,
    "unsubscribes": 5,
    "delivery_rate": 98.8,
    "open_rate": 33.86,
    "click_rate": 4.48,
    "click_to_open_rate": 13.22,
    "first_sent_at": "2019-08-24T14:15:22Z",
    "last_sent_at": "2019-08-24T14:15:22Z"
  },
  "filter_applied": "human_only",
  "status_definitions": {
    "delivered": "Successfully delivered to recipient",
    "bounced": "Permanent failure (5xx error, user unknown, etc.)",
    "failed": "Temporary failure exhausted retries (timeouts, throttling, etc.)",
    "deferred": "Currently retrying temporary failure"
  }
}