Developer Reference

SendSurface Public REST API & Webhooks Documentation

Sync contacts programmatically, check workspace suppression compliance, retrieve campaign statistics, and ingest delivery/bounce webhooks from Amazon SES, SendGrid, Mailgun, or Brevo.

Bearer Token Auth

Every /api/v1/* request requires Authorization: Bearer <API_KEY> scoped to your active workspace.

Suppression Protection

POST /api/v1/subscribers automatically checks workspace global blacklist suppressions and rejects blocked emails with HTTP 400.

Inbound & Outbound Webhooks

Ingest EventBridge, SendGrid, Mailgun, or Brevo notifications and forward HMAC-SHA256 signed events to your own endpoints.

REST API v1 Reference (https://console.sendsurface.com/api/v1)
POST/api/v1/subscribers— Add or update a subscriber in a contact list

Required fields: listId, email. Optional: firstName, lastName, tags, customFields.

curl -X POST https://console.sendsurface.com/api/v1/subscribers \
  -H "Authorization: Bearer YOUR_WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "listId": "your-list-uuid",
    "email": "subscriber@example.com",
    "firstName": "Sarah",
    "lastName": "Vance",
    "tags": ["newsletter", "trial"]
  }'
GET/api/v1/campaigns— List workspace campaigns & authoritative stats
curl https://console.sendsurface.com/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_WORKSPACE_API_KEY"

Inbound Provider Webhooks & Outbound HMAC Signing

Configure your SMTP provider to post delivery, bounce, complaint, and delay webhooks to POST https://console.sendsurface.com/api/webhooks/incoming/:provider/:workspaceId. Supported providers include amazon-ses, sendgrid, mailgun, brevo, postmark, mailjet, smtp2go, mailtrap, mailersend, and sparkpost.