Common Issues

Answers to frequently asked questions about Synapse. If you don't find what you're looking for here, check the specific troubleshooting guides for Flows and Sender Domains.

---

Why isn't my flow triggering?

There are several common reasons:

1. Flow is not active. Check the flow status in the Flows list. Only flows with an "Active" status process events. Draft and Paused flows are ignored.

2. Event name mismatch. The trigger event name must exactly match what your application sends. Names are case-sensitive. Go to Developer Tools > Event Schemas to see the events Synapse is actually receiving.

3. Entry conditions are not met. If your flow has entry conditions, the event's attributes must match all of them. Try temporarily removing conditions to test.

4. Segment is filtering out the contact. If the flow uses a segment, the contact must match the segment criteria at the moment the event arrives. Try removing the segment to test.

5. Idempotency is blocking re-entry. Synapse prevents the same contact from entering the same flow for the same event twice. If you're testing, use a unique idempotency_key with each test event.

6. No events are being received. Check that your application is actually sending events to the correct Synapse API endpoint and that the API key has the data scope.

---

Why was my email suppressed?

An email is suppressed (not sent) when a template variable marked as required has no value.

For example, if your template contains:

And the trigger event doesn't include a Reference Number attribute, the entire email is suppressed to prevent sending an incomplete message.

How to fix:

• Check the event data your application is sending to make sure all required fields are included.
• If the field is optional, remove the required modifier and use a fallback instead: {the Reference Number from the trigger event, or "N/A"}
• Check Email Logs for the "suppressed" status to see which templates are affected.

---

How do I prevent duplicate emails?

Synapse has built-in protections:

1. Idempotency guard. Each event's idempotency_key combined with the flow and contact creates a unique entry. The same combination cannot trigger a flow trip twice.

2. Database constraint. A unique constraint on (flow_id, contact_id, trigger_event_id) prevents duplicate trips at the database level.

If you're still seeing duplicates:

• Check if you have multiple active flows with the same trigger event. Each flow processes events independently.
• Make sure your application sends a consistent idempotency_key with each event. If the key changes (e.g., includes a random value), deduplication won't work.
• If your application retries failed API calls, the idempotency key ensures the retry doesn't create a duplicate trip.

---

What's the difference between a hard bounce and a soft bounce?

---

Why are my emails going to spam?

Several factors can cause emails to land in spam:

1. Sender domain not verified. Make sure your DKIM and SPF records are set up correctly. See Set Up Sender Domain.

2. New sending domain. If you just set up a custom domain, email providers need time to build trust. Start with a small volume and gradually increase.

3. Content triggers. Avoid spam-triggering words in subject lines (e.g., "FREE!!!", "Act now!!!"). Keep your HTML clean and include a plain-text version.

4. High complaint rate. If many recipients mark your emails as spam, your sender reputation drops. Make sure you're only sending to contacts who expect your emails.

5. Using shared domain for marketing. The shared Synapse domain is meant for testing and getting started. For production marketing emails, use a verified custom domain.

---

Why can't I create a new flow (or API key, or invite a member)?

You've likely reached a plan limit. Each plan has maximum numbers for:

How to fix:

• Go to Settings > Billing to see your current usage.
• Either remove unused resources (archive old flows, revoke unused API keys) or upgrade your plan.
• Only the workspace Owner can manage billing.

---

Why isn't my team member receiving the invitation email?

1. Check their spam folder. Invitation emails can sometimes be filtered.
2. Verify the email address. Make sure you typed it correctly when sending the invitation.
3. Check pending invitations. Go to Settings > Team Members and look at the pending invitations section. You can resend from there.
4. Member limit. If you've reached your plan's member limit, the invitation won't be sent. Upgrade your plan or remove an existing member.

---

How do I fix a "Plan limit reached" error?

When you see this error, it means you've hit one of your plan's limits. The error message tells you which limit was reached and your current usage.

Options:

1. Free up resources. Archive old flows, revoke unused API keys, or remove inactive team members.
2. Upgrade your plan. Go to Settings > Billing (Owner only) and choose a higher plan.
3. Wait for reset. Monthly email limits reset at the start of each billing cycle.

---

How do I unsubscribe a contact manually?

Currently, contacts are unsubscribed automatically when:

• Their email hard bounces
• They mark an email as spam
• Your application sends an event that updates their subscription_status to unsubscribed

To manually change a contact's subscription status, your application should send an event with the updated status, which will be synced to the contact record in Synapse.

---

Where can I see detailed error messages?

1. Email Logs. Go to Email Logs and filter by status "Failed" or "Suppressed". Each entry includes an error message explaining what went wrong.

2. Dead Letter Queue. Developer and Admin roles can access Developer Tools > DLQ Viewer to see failed processing attempts with full error details.

3. Flow Trips. Within any flow, the Trips tab shows individual trip records including step execution results and any errors that occurred.