Connect your event sources

Outcome, prerequisites, and source ownership

By the end of this guide, each important source will have an isolated AttuneMail connection, a documented event mapping, and a controlled test proving identity and processing. Bring the event catalog from the previous guide, administrator access to the source, a staging environment, and test customers whose inboxes and records your team controls.

The developer or source administrator owns endpoint configuration, payload integrity, secrets, retries, and cutover. The lifecycle operator owns which provider events are useful, their canonical meaning, and the journeys allowed to consume them. Native connections normalize trusted provider payloads; the Segment-compatible API is the flexible path for application facts and event gateways.

Connect Segment or RudderStack

Create a Segment-compatible server connection and use https://www.attunemail.com/v1 as the data-plane or API base URL. Supply the one-time AttuneMail write key to a server-side destination or trusted gateway. Supported calls are track, identify, group, alias, page, screen, and mixed batch. Do not point a public browser SDK at the endpoint because the credential would be visible to every visitor.

Preserve the producer's original messageId during forwarding and retries. For a gradual cutover, mirror a narrow, non-sensitive event set into a staging connection, compare accepted counts and observed schemas, then verify anonymous-to-known identity. Create a distinct production connection before moving live traffic. Dual delivery is safest when both destinations receive the same logical message ID.

API base URL: https://www.attunemail.com/v1
Authentication: Basic auth
Username: ${ATTUNEMAIL_WRITE_KEY}
Password: <empty>
Preferred transport: /batch
Maximum messages per batch: 500

Connect Stripe billing events

Create a Stripe connection in AttuneMail and copy the native webhook URL shown once. In Stripe, add that exact destination and subscribe only to billing events used by a journey or goal. Begin in Stripe test mode. Do not wrap the body, add a custom schema, or infer marketing consent from checkout; the native route expects the provider payload and performs the provider-specific normalization.

Stripe event types become stripe.{event.type}. The Stripe event ID supplies idempotency. AttuneMail uses data.object.customer as an external customer identifier when present and considers customer_email or email fields for identity traits. Verify the mapping with checkout completion, subscription update, and payment failure examples before deciding which event is a trigger versus a diagnostic signal.

1. 01

   Separate test and live mode

   Use different AttuneMail connections so test billing records cannot enroll production customers.

2. 02

   Select a narrow event set

   Subscribe to lifecycle facts you have defined, not every Stripe event available.

3. 03

   Inspect identity

   Confirm the Stripe customer and email resolve to the intended controlled customer.

4. 04

   Prove consent remains independent

   Confirm a payment event can be observed while a suppressed customer remains ineligible to send.

Connect Clerk account events

Create a Clerk connection, copy the one-time native webhook URL, and add it as a Clerk webhook endpoint. Select only user or session events that represent a documented lifecycle fact. Send the untouched Clerk body. Event types become clerk.{event.type}; AttuneMail prefers the svix-id header, then a payload ID, then a stable payload hash to identify a repeated delivery.

When present, the user ID and primary email are extracted from data. Test with a non-production account and compare the resolved customer to your application user ID strategy. clerk.user.created can start account onboarding, but it should not serve as proof of marketing permission. Choose a product outcome such as onboarding.completed as the journey goal so onboarding stops when value is reached.

Connect Supabase database changes

Create a Supabase connection and configure a Database Webhook for the schemas, tables, and operations that represent real lifecycle facts. Send the native insert, update, or delete payload to the one-time URL. Names normalize to supabase.{schema}.{table}.{operation}, which makes the database lineage explicit. Restrict the webhook rather than streaming unrelated or sensitive tables.

AttuneMail examines record or old_record fields for likely IDs and email values, but implicit extraction is not a substitute for a reviewed model. Confirm which row represents the person, which represents an account, and whether an update is meaningful enough to emit. Database changes can be noisy; prefer a purpose-built outbox or view when a raw row update would create repeated or ambiguous lifecycle events.

-- A narrow source-of-record view for lifecycle qualification
create view lifecycle_onboarding_completed as
select owner_user_id, plan, onboarding_completed_at
from workspaces
where onboarding_completed_at is not null;

Validate, cut over, and troubleshoot

For every connection, record its environment, source administrator, credential or URL rotation procedure, subscribed events, identity extraction, consent interpretation, expected volume, and consuming journeys. Send controlled examples, inspect source lineage and observed schemas, repeat a delivery to prove idempotency, and verify an unresolved identity is retained for diagnosis without starting a journey.

If a provider reports success but no usable event appears, compare environments, inspect the exact destination, search by provider event ID, and check whether identity could be resolved. A rotated or paused connection rejects new deliveries. An accepted provider payload can still fail normalization if required structure is missing. Keep the source's delivery log and AttuneMail processing record together during incident review.

The next guide is the public API contract for teams building or operating direct producers. It covers all and only the customer event routes, authentication choices, request limits, batching, idempotency, retry decisions, and tooling generated from the deployed OpenAPI document.