Mailcoach - Setup Guide

Overview

The Mailcoach source syncs campaign, audience, engagement, unsubscribe and bounce data into Daspire-managed pipelines.

This is a Daspire-owned source connector. Customer-facing APIs use Daspire product ids. Use conn_mailcoach_sellersync_edm as the primary connector_id.

Legacy runtime ids such as source:efd2f044-dcbb-52ee-98d0-c169d9d092b9 are accepted only for old URLs or saved configurations that still contain runtime-style ids.

Prerequisites

• A Mailcoach account.
• A Mailcoach bearer token with read access to email lists, campaigns and campaign engagement detail.
• The HTTPS API base URL:
  • Self-hosted Mailcoach: your Mailcoach instance API URL ending in /api.
  • Mailcoach Cloud: your hosted account API URL in the form https://[your-domain].mailcoach.app/api.

Configuration

Field	Required	Notes
Connection Method	No	Defaults to Self-hosted. Use Mailcoach Cloud for hosted *.mailcoach.app accounts. Existing configs that do not include this optional field continue to work.
API Base URL	Yes	Enter this value manually. Must be an approved HTTPS Mailcoach API host. Plain HTTP, localhost, private hosts, credentials in URLs, query strings, fragments and non-default HTTPS ports are rejected. For self-hosted Mailcoach, enter the customer's own instance API URL ending in /api; for Mailcoach Cloud, use https://[your-domain].mailcoach.app/api.
API Token	Yes	Stored as Daspire secret material and never returned by product APIs.
Campaign Status	No	Defaults to sent. Other values are scheduled, draft and all.
Page Size	No	Defaults to 100 records per request; maximum 5,000. Mailcoach may apply a lower endpoint-specific cap and the connector follows returned pagination metadata.
Campaign email content (campaign_content_mode)	No	inline (default) preserves existing campaign records including email content. omit keeps campaign metadata and metrics without email content. separate moves the content to the optional campaign_content stream. Requires a connector release exposing this setting.
max_pages_per_batch	No	Defaults to 100 engagement pages between resumable checkpoints.
max_snapshot_pages	No	Defaults to 1,000 pages per complete email-list/campaign identity scan; range 2–1,000. This is separate from engagement batches because a provider may return fewer records than the requested Page Size.

Supported Streams

Stream	Description
email_lists	Mailcoach email list metadata.
campaigns	Campaign records and campaign-level metrics.
campaign_clicks	Click detail rows grouped by campaign.
campaign_opens	Open detail rows grouped by campaign.
campaign_unsubscribes	Unsubscribe rows grouped by campaign.
campaign_bounces	Bounce rows grouped by campaign.
campaign_content	Optional email content archive, available only with campaign_content_mode=separate. Join to campaigns using campaign_uuid (or uuid).

For daily reporting, use campaign_content_mode=omit and keep the metrics and engagement streams you need. This excludes the campaign fields html, structured_html, email_html and webview_html; other metadata, custom fields, metrics and engagement details are preserved. It does not remove existing rows or content already stored in your destination.

If you need an email archive, choose separate and explicitly select campaign_content when you want to read it. That stream contains the campaign UUID, list UUID, modification timestamps when available, and the four email content fields. It writes independently of campaigns. Leaving it unselected avoids retaining or exporting campaign content. Selecting both streams shares the same campaign inventory without an extra provider scan for the archive.

All streams still use full refresh, including the optional archive. Each completed scheduled cycle scans history again; checkpoints resume interrupted cycles and are not incremental cursors. Content separation reduces connector cache and destination payloads when the archive is unselected. On the upgraded provider, metrics-only reads also request slim campaign pages so the four email content fields are not serialized or transferred. Older compatible providers may still return those fields; the connector removes them locally. Repeated append cycles require a downstream snapshot/deduplication policy. Do not change a shared destination table to overwrite to solve repeated scans. True incremental reads require a verified upstream campaign/event cursor API.

The upgraded provider also shortlists campaigns that actually contain opens, unsubscribes, or bounces and exposes campaign links through one paginated endpoint. The connector uses those capabilities automatically, with safe fallback to the prior per-campaign reads when an older provider returns 400 for the shortlist or 404 for the links endpoint. This reduces request count; it does not change any stream from full refresh to incremental.

Mailcoach exposes campaign-level EDM metrics natively. Traffic and sales attribution require UTM or internal attribution joins outside Mailcoach.

Campaign snapshots retain every field using bounded lossless in-memory compression; large campaign bodies are decoded only for the current output batch or campaign. Pagination convergence, UUID-based resume and complete-stream checkpoints are preserved. Campaign output batches also have a roughly 4 MiB payload budget; this changes batch size, not the records selected for a full sync.

The connector fails without accepting completion if a response exceeds 8 MiB, an individual snapshot record exceeds 8 MiB, or a compressed snapshot exceeds 64 MiB. For provider_response_too_large, reduce Page Size where the provider supports it. An explicit snapshot page/memory limit error must be resolved; retrying the same request does not turn a partial scan into a successful complete sync.

Migration And Rollback

This connector is added as a new source definition and does not migrate customer connections automatically.

Existing source ids, destination ids, pipeline ids, job ids, selected catalogs, schedules, state, billing and usage behavior are unchanged. Existing _daspire_* warehouse naming is unchanged.

Rollback removes the new Mailcoach source definition from customer setup while leaving existing customer connections and all legacy connector code untouched.

Saving content settings on Native connections

After the content-capable connector and Control update are deployed, save only {"configuration":{"campaign_content_mode":"omit"}} through the source settings API or the existing daspire_update_source MCP tool. Use inline to restore content in future campaign records, or separate for an optional archive. This save preserves credentials, page size, campaign status, selected streams, checkpoints, destinations and each dependent connection's schedule. It does not start a sync or remove historical content already stored at the destination.

If the source's image or schema is not ready, the save returns MAILCOACH_CONTENT_RUNTIME_NOT_READY without changing settings. Remove the campaign_content stream from the source stream filter and dependent catalogs before switching away from separate. Submit changes to other settings separately. If a save returns SOURCE_REAUTH_INTERRUPTED or SOURCE_REAUTH_RECONCILE_REQUIRED, scheduling needs support reconciliation; do not repeatedly submit the same change.

Change email content storage on an existing source

Open Sources → your Mailcoach source → Settings → Campaign email content. Once the connector upgrade is ready, choose Keep metrics only (recommended) and use the form’s Save changes button. The option uses the same dropdown and form layout as the other settings. Changing this option alone updates only campaign_content_mode; existing credentials, stream selection and sync cadence remain unchanged. A successful save is shown only after reading the stored setting back. If the save cannot be confirmed, refresh to inspect the current value before retrying.

The field appears when the server declares support. Reopening settings or returning to the browser refreshes the connector schema after an upgrade. Runtime admission and dependent connection catalogs are also checked when saving. To leave separate mode, first deselect campaign_content in dependent connections and any source stream filter. Omit mode keeps full-refresh semantics while avoiding email-body transfer when the provider supports the slim campaign response. The connector upgrade uses the common source release process; a connection retry continues using its original task's version.

A published connector upgrade keeps this setting available when the active image and the source's pinned schema match their release registry hashes. Users choose the content mode themselves; publishing an upgrade does not change their setting. An image-only pointer change with a stale schema/image binding is rejected.

The settings API uses the published Native source schema, so a retired connector specification cannot hide options introduced by a qualified upgrade.