Changelog

Stay up to date with the latest changes to the SuperSend API. We follow semantic versioning and announce breaking changes in advance.

April 2026

April 16, 2026 - Senders: unsubscribe reply forwarding control

April 14, 2026 - Client costs: revenue/margin deferred

April 13, 2026 - Client Costs (COGS) API

New billing endpoints for per-team cost attribution beyond SuperSend charges:

MCP: get_client_costs, list_cost_items, create_cost_item, delete_cost_item tools added (update_cost_item added April 14).

April 13, 2026 - List contacts: last_activity and last_updated sort

GET /v2/contacts — sort_by last_activity / last_activity_asc now use the most recent Events timestamp for the contact (all channels and event types), not only email sent/opened/replied. New: last_updated and last_updated_asc sort by contact updatedAt. MCP: list_contacts accepts the same sort_by values.

April 9, 2026 - Contact import inbound webhook: plain text responses

POST /v1/contact-import/:teamId/:token (breaking for JSON consumers) — Successful and error responses now use Content-Type: text/plain; charset=utf-8 with a short body only, for example:

The previous JSON shape (success, mapping_configured, processed, created, updated, failed, errors, sample_source_keys, etc.) is no longer returned. If field mapping is not configured, the handler still accepts the body and stores the first payload as before; use GET /v1/contact/.../import-webhooks/:id in the app to inspect keys and mapping.

April 9, 2026 - Contact import inbound webhook: 200 when mapping is missing

POST /v1/contact-import/:teamId/:token — If field mapping is not configured yet, the handler accepts the JSON body (first payload / firstPayloadAt / firstPayloadBody unchanged) and returns 200 (now plain text; see entry above). Previously this case returned 422.

When mapping exists and some rows cannot be saved as contact profiles, the HTTP response is plain-text Error. (200); the webhook creator may receive an in-app notification (throttled to at most once per 15 minutes per webhook for failure summaries). When the first payload is stored and mapping is still missing, the creator may receive an in-app notification to configure mapping.

April 9, 2026 - List contacts: sort_by with current_step, time in step, bulk action recoverability

GET /v2/contacts sort_by now also accepts current_step and current_step_desc. Sorting uses numeric step order only (legacy: Contact.next_step; flow: data.step_number on the node matching Contact.next_node, then next_step), not step titles. Finished contacts are ordered after all in-progress contacts so they are not interleaved with the same step number they ended on.

The campaign Contacts UI shows time in current step (e.g. "3 days in step") inside the Current Step column, using last_node_processed_at. After bulk actions, the same sticky row as bulk selection shows a short confirmation with View them to re-select the affected contacts.

April 8, 2026 - Playbooks: delete and permanent removal

DELETE /v2/playbooks/:id — Without permanent, sets the playbook status to archived (soft delete). With query permanent=true, permanently removes the playbook row; only allowed when the playbook is already archived. Linked campaigns are not deleted; PlaybookId on those campaigns is cleared (SET NULL). Soft-delete responses include message (Playbook archived) with data, consistent with OpenAPI.

MCP tool: delete_playbook.

April 8, 2026 - Playbooks: duplicate

POST /v2/playbooks/:id/duplicate — Creates a new draft playbook with the same offer, segment, messaging, and hypothesis as the source. Does not copy linked campaigns or outcome notes. Optional body name; default name is Copy of {original}.

MCP tool: duplicate_playbook.

April 8, 2026 - List contacts: sort_by and has_email_sent filter

GET /v2/contacts now supports:

The MCP list_contacts tool also accepts sort_by.

April 8, 2026 - Per-campaign bounce guard threshold

POST /v2/campaigns, PATCH /v2/campaigns/:id, GET /v2/campaigns/:id, and GET /v2/campaigns now support a new field bounce_guard_max_rate (float, 0.01–0.25, default 0.1). Each campaign has its own bounce rate auto-pause threshold — the campaign is automatically paused when the invalid-recipient bounce rate exceeds this value. Default is 10%. A warning is shown in the campaign settings UI when users set this above 10%.

April 3, 2026 - Create contact: profile-first enrollment and optional labels

POST /v2/contacts — With CampaignId, the API now explicitly upserts ContactProfile and ContactTeam before creating or updating the enrollment (Contact), aligning the documented flow with runtime behavior. Optional labels (array of strings) attaches existing org/team labels to the profile (applies_to contact or both); unknown names and conversation-only labels are ignored.

Docs updated: Contact API, V2 API overview, Migration guide, docs home, api/V2_API_DEVELOPER_GUIDE.md, and api/openapi.yaml.

April 3, 2026 - Intelligence: sender health uses invalid-recipient bounces only

GET /v2/intelligence/sender-health-summary (and sender_health inside deliverability diagnosis) now treats bounces, bounce_rate_percent, at_risk, and summary total_bounces / overall_bounce_rate_percent as invalid-recipient (list-quality) bounces only, consistent with the in-app sender health score and sender list bounce rate.

New fields: per-sender all_bounces and summary total_all_bounces for the count of all bounced sends in the window (soft, policy, invalid, uncategorized). Integrations that relied on the previous “any bounce” meaning for bounces should use all_bounces / total_all_bounces instead.

See API changelog.

April 3, 2026 - Team summary: Deliverability tab generally available

The Deliverability tab on Team summary is shown for all organizations (no deliverability_dashboard_enabled check in the app). The deliverability_dashboard_enabled feature flag row is removed from the database when the corresponding migration runs, along with related assignments and usage, so internal-admin no longer exposes a dead toggle.

See API changelog.

April 3, 2026 - Automated placement testing: available for all organizations

V1 placement tests — auto settings (GET / PATCH /v1/placement-tests/auto-settings) and sender auto-schedule (GET /v1/placement-tests/auto-schedule/sender/:senderId) no longer require the auto_placement_test_enabled feature flag or an enterprise org. Any org can enable team-level automated placement testing (subject to plan credits and existing permissions). The NOT_ENTERPRISE error is no longer returned from PATCH .../auto-settings. Response field settings.isEnterprise remains for compatibility and is always true.

The auto_placement_test_enabled feature flag row is removed from the database when the corresponding migration runs.

See API changelog.

April 3, 2026 - Playbooks: available without feature flag

Playbooks (/v2/playbooks and campaign PlaybookId on create/update) no longer require the playbooks_enabled feature flag or a @supersend.io email. Access follows normal authentication and team membership rules for each endpoint.

See API changelog.

April 3, 2026 - Deliverability summary: bounce_types from events

GET /v2/intelligence/deliverability-summary — bounce_types is now aggregated from Events.bounce_subtype (with bounce_category on each row) instead of a separate AI-task join, so subtype counts align with bounce_categories. percentage on each bounce_types item is the share within that bounce category bucket (not across all bounces). New bounces populate bounce_subtype from provider reason text and from AI classification when available.

See API changelog.

April 1, 2026 - Outbound Playbooks

New Playbooks endpoints let teams capture the strategy behind their campaigns — the offer, target segment, messaging angle, hypothesis, and outcome notes. Campaigns link to playbooks optionally; performance (sends, replies, reply rate, interested, meetings booked) rolls up automatically from linked campaigns.

MCP tools: create_playbook, list_playbooks, get_playbook, link_playbook_campaigns.

See API changelog.

April 1, 2026 - Team contact profile detail: associated_campaigns enrollment payload

GET /v1/contact/profile/:profileId (query TeamId required) — the returned contact / Contact object includes associated_campaigns: one object per campaign that has an enrollment (Contact) linked to this ContactProfile.

Each item includes ContactId, contactCreatedAt (ISO timestamp of the enrollment row; list sorted newest first), per-campaign flags (replied, bounced, unsubscribed, opened, clicked, finished, appointment), interest, queue status, next_step, pause fields, failed, reason, last_node_processed_at. If multiple enrollment rows exist for the same campaign + profile, the row with the latest createdAt is used.

OpenAPI: AssociatedCampaignEnrollment and TeamContactProfile.associated_campaigns document the shape; GET /v2/contacts/{id} description notes the difference between enrollment id and profile id.

See Contact API and api/openapi.yaml.

April 1, 2026 - Webhooks: delivery list includes payload; app testing and logs UX

GET /v2/webhooks/{id}/deliveries — each delivery in the list may include payload: the JSON body that was sent (or would be sent) for that attempt, when stored. Same field is available from the app’s team integration delivery logs (GET /team/integrations/:id/webhook-deliveries).

SuperSend app (Integrations): sample and real-contact webhook tests use a production-shaped JSON body (aligned with live maybeSendWebhook payloads, including event-specific blocks, app_url, org, team, and test: true). Test → appears next to each subscribed event. Webhook delivery logs include View Payload (modal with copyable JSON).

See Webhooks.

April 1, 2026 - Webhook delivery logs: search filter by contact email

GET /v2/webhooks/{id}/deliveries accepts optional search — case-insensitive partial match on the linked contact email. The app’s team integration delivery logs use the same behavior via GET /team/integrations/:id/webhook-deliveries?search=.

April 1, 2026 - Webhooks: reply and linkedin_reply include AI category, mood, and confidence

Email reply webhook POST bodies now include reply.category, reply.mood, and reply.confidence when the inbound message was classified by SuperSend’s email AI (same values stored on the conversation for triage).

linkedin_reply payloads include the same three fields under linkedin (linkedin.category, linkedin.mood, linkedin.confidence) when LinkedIn AI classification runs before the webhook (org has AI enabled; real-time classify succeeds). If classification is unavailable, the webhook is unchanged aside from optional omission of those fields.

See Webhooks (Reply Events and LinkedIn Reply Events).

April 1, 2026 - Campaign pause: clear stale allocation Redis keys and zero DB snapshot

When a campaign stops sending (user pause, bulk pause, archive, auto-pause paths that use Campaign.save / selected bulk updates, or org deactivation), the API now removes per-campaign allocation/demand Redis keys matching campaign:, campaign_alloc:, alloc:email:, alloc:li:, alloc:tw:* for that campaign, and appends a zeroed CampaignCapacityAllocations row (except org deactivation, which uses org-wide Redis clear only to avoid mass DB writes). This aligns runtime counters and latest DB snapshots with inactive campaigns without waiting for the next org allocation tick.

April 1, 2026 - Capacity planning: inactive campaigns show zero allocated email capacity

GET /v2/intelligence/capacity-summary and GET /team/summary-capacity-planning — for campaigns that are not sending (status inactive), allocatedCapacityPerDay is now 0 and emailPotentialCapacity is omitted for forecasting, instead of reusing the last CampaignCapacityAllocations row from when the campaign was active. Allocation jobs only run for sending campaigns, so those rows were stale and made Planning look like inactive campaigns still held daily capacity.

March 2026

March 31, 2026 - Contact profile labels (V2 + MCP)

Contact OS (Phase 1): org-scoped ContactProfile can carry team-compatible labels via the existing Labels + ContactProfileLabels junction. Each junction row includes OrgId and TeamId. Labels.applies_to (conversation \| contact \| both, default conversation) controls whether a label is for Super Inbox, contact profiles, or both. GET /v2/labels accepts label_purpose (conversation, contact, all).

New V2 endpoints (contact must have email, linkedin_url, or twitter so a profile can be resolved; label must belong to the org, and team-scoped labels must match the contact's team):

MCP: list_contact_profile_labels, assign_contact_profile_label, remove_contact_profile_label.

Email validation / intelligence: validation and global intelligence fields are also mirrored onto ContactProfile from validation jobs and updateContactIntelligence so profile state stays aligned with Contact.

See API changelog and api/openapi.yaml.

March 31, 2026 - Capacity summary: correct active counts and list filters

GET /v2/intelligence/capacity-summary (and app GET /team/summary-capacity-planning) — overview.activeCampaigns, overview.noCapacityCount, and overview.totalContactsRemaining now use campaign sending status (active = status sending) aligned with the Planning table’s Active filter (sending, contacts not finished, has capacity). noCapacityCount previously could never increment due to a logic bug; it now counts sending campaigns with no allocated capacity.

New optional query parameters:

limit maximum is 200 per request for this endpoint.

Response: completionForecastChart — up to 10 { id, name, projectedCompletionDays } rows for the whole team (campaigns with a finite completion estimate), stable regardless of planningFilter, search, or pagination.

See API changelog.

March 31, 2026 - Inbox auto-reply rules available for all organizations

GET /team/inbox-settings and PUT /team/inbox-settings (app API) always include and accept autoReplyRules / auto_reply_rules. The org-scoped feature flag inbox_auto_replies_enabled is removed from the product path; auto-reply rules still run after AI categorization when configured on the team.

See API changelog.

March 31, 2026 - Campaign outbound attachments in conversation threads

Successful campaign email sends (SMTP, Gmail, Outlook, Mission Inbox, SendGrid, Mailreef, mailserver, etc.) now persist attachment snapshots on the corresponding ConversationMessage: per-contact files from custom_attachment_vars (after download) are uploaded to org-scoped storage; static attachments already on SuperSend S3 under the sender’s team/org are referenced without duplicating bytes. The create_sent_message_conversation worker writes ConversationMessageAttachment rows so Super Inbox matches what was sent.

GET /v2/conversations/:id/messages — same attachments array as before; campaign-sent rows appear when snapshots exist.

See API changelog.

March 30, 2026 - Conversation message attachments in V2 list

GET /v2/conversations/:id/messages — each item may include attachments: { id, filename, file_path, cloud_url }[] when the message has stored files (inbound mail sync or outbound Super Inbox replies).

Behavior: After a queued inbox reply sends successfully, attachments uploaded in the composer are now saved as ConversationMessageAttachment rows on that message (same as inbound), so Super Inbox can list and download them.

See API changelog.

March 27, 2026 - Campaign lifecycle history (latest_lifecycle_event)

GET /v2/campaigns/:id and GET /v1/campaigns/:campaignId/dashboard ( campaign.latest_lifecycle_event in the JSON body ) may include latest_lifecycle_event: the most recent lifecycle row (started / paused), optional reason_code (e.g. user, invalid_recipient_bounce_rate, plus many system codes such as schedule_no_email_senders, billing_email_limit, failure_config_pause_campaign, org_deactivated, team_deleted, SMTP/Twitter/LinkedIn automation reasons), occurred_at, optional actor (user who started or paused), and optional metadata. Rows are stored in CampaignLifecycleEvents for future full-history UI.

See Campaigns and API changelog.

March 27, 2026 - Campaign bounce_checkpoint_at

GET /v2/campaigns, GET /v2/campaigns/:id, and PATCH /v2/campaigns/:id responses may include bounce_checkpoint_at (nullable date-time). It marks the start of the window used for automated invalid-recipient bounce monitoring: it is updated when a campaign is started (inactive → active), or when Restart contacts runs for that campaign. The guard (server-side) only counts email sends on/after the checkpoint, excludes sends newer than ~15 minutes (so bounces can classify), requires more than the configured minimum sends (100 in production by default), and if send volume in the last 24 hours exceeds 500, it evaluates rate using only that rolling 24h window; otherwise it uses the full range from the checkpoint. Thresholds live in config.invalidRecipientBounceGuard (env-tunable).

See Campaigns and API changelog.

March 26, 2026 - Sender reply forwarding rules (forward_rules)

Senders now support per-destination reply forwarding with optional Super Inbox label filters, in addition to the existing forward_to field.

Affected endpoints:

Behavior:

See Senders in the API reference (OpenAPI Sender and UpdateSenderRequest schemas) for field shapes.

March 24, 2026 - Team notification email with per-category preferences

PATCH /teams/:id now accepts two new fields:

GET /teams/:id and GET /teams responses now include both fields.

Documentation: Teams (see API changelog)

March 23, 2026 - Sender provider values aligned with connect flow

POST /sender (V1) accepts the same provider values the app uses for preset mailboxes and email APIs (e.g. zoho, namecheap, mailgun, aws, azure), so connect no longer fails Joi validation for those options.

GET /senders — provider query filter accepts the expanded set (including ss-private-smtp, sendgrid, mailreef, infraforge, and the preset providers above). OpenAPI Sender.provider and list-filter docs are updated.

Documentation: Senders (see API changelog)

March 23, 2026 - Email validation now includes intelligence data

POST /email-validation/verify response now bundles email intelligence fields alongside the SMTP deliverability result—risk score, confidence level, provider detection, bounce/reply history, and flag signals (role-based, free provider, disposable). No additional credit is charged; one verification credit unlocks both data sets, matching the in-app experience.

Documentation: Email validation API

Use cases: Clay columns, Make/Zapier, enrichment pipelines, internal scripts.

March 19, 2026 - Mailbox purchase: recipient name required

POST /mailboxes/purchase (and related purchase flows) now require first and last name for the mailbox recipient. Applies to quotes and checkout aligned with registrar requirements.

Documentation: Managed Mailboxes

March 18, 2026 - Campaign V2 documentation and OpenAPI alignment

Campaign endpoints, request/response examples, and schemas in api/openapi.yaml were updated for consistency with live V2 behavior. See Campaigns.

March 17, 2026 - Announcements (unauthenticated)

GET /announcements returns active in-app announcements (manual and status-driven). Intended for the app shell; does not require authentication.

March 14–16, 2026 - Optional email verification on contact create (validate_emails)

Documentation: Contacts

March 12, 2026 - Campaign daily send ceiling (max_per_day)

Campaigns support max_per_day: an optional maximum number of emails sent per day from all senders in the campaign. null means no campaign-level cap (sender limits still apply).

Documentation: Campaigns

March 10, 2026 - Team usage and org billing views

March 6, 2026 - Placement tests (V2 OpenAPI parity)

Placement test endpoints are documented in the OpenAPI spec with V2 response patterns. See Placement Tests.

March 3, 2026 - List Health: selector and API alignment

List Health behavior and docs were aligned with V2 (including selector updates so teams do not pick unusable states). See Campaigns.

March 2, 2026 - Contact status: customer

Contact interest / status filters include customer for contacts marked as customers. See Contacts.

February 2026

February 28, 2026 - Campaign categories and create-campaign parity

Campaign categories (folders) APIs and docs were finalized. Creating a campaign via V2 now ensures ContactConfig is created in line with V1 behavior.

Documentation: Campaign Categories, Campaigns

February 25, 2026 - Intelligence composite endpoints

Aggregate Intelligence endpoints were added for capacity, deliverability, sender health, outbound summary, and domain health (supporting MCP tools and internal automation). See the Intelligence tag in api/openapi.yaml and MCP Server.

February 24, 2026 - Conversations API (V2)

Conversation endpoints for the unified inbox (email, LinkedIn, Twitter), including messages and participant metadata.

Paths: GET/POST /conversations, GET /conversations/{id}, GET/POST /conversations/{id}/messages

Documentation: Conversations

February 23, 2026 - Managed domains and mailboxes (purchase)

Documentation: Managed Domains, Managed Mailboxes

February 17, 2026 - Team settings: inbox_super_views

GET and PATCH /teams/{id} include inbox_super_views for team-level inbox display settings (V2 parity).

Documentation: Teams

January 2026

January 28, 2026 - Campaign Contact Lifecycle Metrics

Added contact_metrics to V2 campaign endpoints for tracking contact lifecycle status.

Affected Endpoints:

New Fields:

{
  "contact_metrics": {
    "total": 150,
    "not_started": 50,
    "in_progress": 75,
    "finished": 20,
    "paused": 5
  }
}

Use Cases:

January 27, 2026 - V2 Bulk Contacts Endpoint

Added POST /v2/contacts/bulk for bulk importing contacts with V2 standardized responses.

Features:

curl -X POST 'https://api.supersend.io/v2/contacts/bulk' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 700 dark:text-green-400">'{"contacts": [...], "TeamId": "...", "CampaignId": "..."}'

January 19, 2026 - V2 API General Availability

The V2 API is now generally available! This release brings significant improvements to consistency, error handling, and developer experience.

New Features:

Breaking Changes from V1:

// V2 Response Format
{
  "success": true,
  "data": { ... },
  "request_id": "req_abc123"
}

December 2025

December 12, 2025 - Email Analytics

November 2025

November 28, 2025 - Campaign Improvements

November 15, 2025 - Sender Profiles

November 8, 2025 - Security Updates

October 2025

October 25, 2025 - V2 API Beta

The V2 API entered public beta with the following endpoints:

October 18, 2025 - Bulk Operations

October 10, 2025 - Error Handling

API Versioning Policy

Supported Versions

Breaking Changes

We consider the following to be breaking changes:

Non-Breaking Changes

The following are considered non-breaking and may be made without notice:

Deprecation Notices

V1 API Deprecation

The V1 API is deprecated and will be sunset on December 31, 2026. Please migrate to V2 before this date.

Timeline:

See the V1 to V2 Migration Guide for detailed migration instructions.

Need Help?