REST API v1

Events API

A unified API for delivery events, suppressions, and integrations. Provider-agnostic, webhook-ready, built for scale.

Base URL

https://tweak.email/api/v1

Authentication

Authorization: Bearer <your-api-key>

Or use the X-Api-Key header. Generate your key in Settings.

Endpoints

Events

POST /events Ingest delivery events

Record one or more delivery events. Events are processed through the unified pipeline: campaign stats are updated, suppressions are auto-created for bounces/spam/unsubscribes, and contact statuses are synced.

Request Body

{
  "events": [
    {
      "email": "jane@example.com",
      "event": "delivered",
      "campaign_id": 42,
      "contact_id": 1337,
      "provider": "sendgrid",
      "source": "webhook",
      "metadata": { "response": "250 OK" }
    }
  ]
}

Event Types

delivered bounced deferred dropped spam_report unsubscribed opened clicked queued sent

Response

{ "status": "ok", "processed": 1 }

Suppressions

GET /suppressions List suppressions

Retrieve your suppression list with optional filters. Paginated.

Query Parameters

reason Filter: hard_bounce, spam_report, unsubscribe, manual email Exact match on email address per_page Results per page (default: 100)

POST /suppressions Add a suppression

Manually add an email to the suppression list. Upserts if the email already exists.

Request Body

{
  "email": "bounced@example.com",
  "reason": "hard_bounce",
  "metadata": { "note": "Permanent failure" }
}

DELETE /suppressions Remove a suppression

Remove an email from the suppression list. The email will be eligible for future sends.

{ "email": "reactivated@example.com" }

Concepts

Unified Event Pipeline

All delivery events — from SendGrid webhooks, Resend, your own native sends, or API calls — flow through a single pipeline.

Campaign stats updated automatically
Auto-suppress on bounce, spam, unsubscribe
Contact statuses synced in real time
Switch providers, keep your history

Reverse ETL

Connect your BigQuery data warehouse and use live data in your campaigns — no CSV imports, no data copies.

OAuth with read-only BigQuery scope
Browse datasets, tables, and columns
Map columns to email placeholders
Data queried live at send time

Rate Limits

The API is rate-limited per team.

Events	1,000 events/request
Suppressions	100 requests/min

Error Responses

Standard HTTP status codes with JSON error bodies.

401	Missing or invalid API key
403	Invalid API key
422	Validation error
429	Rate limit exceeded

Ready to integrate?

Generate your API key in Settings and start building.

Get Your API Key — Free