Migrate from Intercom

​

Mapping Intercom Concepts to Courier

​

Series and Journeys

• Batch and digest nodes collapse many events into one message. In Intercom, roll-up messages have to be precomputed in your own backend before you fire the triggering event.
• Fetch data nodes call an external API mid-journey and use the response in later steps.

​

Event-Triggered Messages and the Send API

# Intercom: fire an event and let a pre-configured rule match it
curl -X POST https://api.intercom.io/events \
  -H "Authorization: Bearer $INTERCOM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "password_reset_requested",
    "created_at": 1755500000,
    "user_id": "user_123",
    "metadata": { "reset_url": "https://app.example.com/r/abc123" }
  }'

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "password-reset",
      "data": { "reset_url": "https://app.example.com/r/abc123" }
    }
  }'

• Intercom caps a workspace at 120 active event names, and each event can drive at most 50 live proactive support messages. Courier templates are addressed by ID, so there is no shared namespace to run out of.
• Intercom events are flat; its API docs state that nested JSON structures are not supported. Courier data and user profiles both take arbitrary nested JSON, so an order with line items goes through as-is.
• Intercom de-duplicates events on workspace, contact, event name, and created_at at second granularity, and drops duplicates with a 202. Two legitimate identical sends in the same second collapse into one. Courier treats every send request as its own message.
• New Intercom event metadata can take up to 24 hours to become available in the message composer and filters. Courier templates reference variables directly, so a new field is usable on the next send.
• An Intercom outbound message can carry only one event-based rule, and event-triggered messages are not eligible for re-notification.

​

Transactional Sending

​

Contacts, Custom Attributes, and User Profiles

​

Keeping Intercom for Support

1. Your application is the source of truth for who the user is and what they did.
2. Into Courier: upsert profiles with identifiers, channel addresses, and the attributes you segment or personalize on.
3. Into Intercom: keep sending the contact updates and events your support team relies on for context in the Intercom Inbox.

​

Subscription Types and Preferences

​

Frequency Capping

​

In-Product Messages

• Posts and News items map cleanly to Courier Inbox messages.
• Banners are on the Courier roadmap as a first-class in-app surface. Until they ship, either keep banners in Intercom or render one in your own UI over Courier Inbox data. If banners are load-bearing for you, scope them separately from the rest of the migration rather than blocking the cutover on them.
• Tooltips, Checklists, Product Tours, and Carousels are in-product guidance and onboarding UI. Those stay in Intercom or move to a product-adoption tool. Courier does not replace them.

​

Personalization and Localization

​

Authentication

​

Migration Plan

​

Phase 1: Inventory

1. List every live outbound message and Series. Note the trigger, channels, and audience for each. No endpoint returns Series definitions, so take these from the Outbound list filtered to live messages. For per-message volume, POST /export/content/data exports delivery and engagement data for outbound content, Series included, over a date range. One active job per workspace.
2. Split the list into transactional, marketing, and in-product. Transactional is anything a user action must produce: password resets, receipts, confirmations, alerts. In-product is banners, tours, tooltips, and checklists, which stay in Intercom or move elsewhere.
3. List the events you fire. Mark which ones exist only to trigger a message and which ones your support team reads in the Intercom Inbox. The first group retires; the second stays.

​

Phase 2: Transactional

4. Connect your providers. Add your email, SMS, and push provider credentials in Courier and verify your sending domains. You are moving off shared IPs, so check domain authentication before the first production send.
5. Set up the profile sync. Upsert user_id, channel addresses, and the attributes your templates need. Start registering push tokens with Courier from your app now, in parallel with the Intercom SDK, so tokens accumulate ahead of the push cutover.
6. Rebuild the highest-volume transactional templates in Design Studio, with content for each channel the message sends on.
7. Replace event posts with send calls. Each POST /events that existed only to trigger a message becomes a POST /send naming the template and passing data. This is usually a small diff and it removes an indirection: the call now returns an ID you can trace to delivery status.
8. Run in parallel and compare. Send to a test audience through both systems, diff the rendered output, then cut over one message type at a time. Watch the logs rather than the calendar.

​

Phase 3: Preferences

9. Map Subscription Types to preference topics, decide the default for each, and import opt-outs before any marketing send. Do this before Phase 4, not during it.

​

Phase 4: Marketing

10. Rebuild Series as journeys, starting with onboarding. Recreate the trigger, then the nodes. Where a Series precomputed a roll-up in your backend, replace that with a batch or digest node.
11. Convert segments to audiences. Segment rules become audience filters on profile attributes, and membership updates on its own as profiles change.
12. Move one-off sends to broadcasts: pick a template, pick an audience, send now or schedule it.
13. Add frequency caps. Per-message rules in Intercom become send limits that hold across every journey and broadcast.

​

Phase 5: Decommission

14. Pause the Intercom message, don’t delete it, once its Courier replacement has run clean for a full cycle.
15. Drop the Proactive Support Plus add-on when no live message needs it, and stop firing the events that existed only to trigger sends.

​

Migrating with an AI Agent

• Courier Skills teaches the agent Courier’s real APIs and patterns so it stops guessing at endpoints:
  npx skills add trycourier/courier-skills
  
  In Claude Code you can install it as a plugin instead, which self-updates and ships the Courier docs MCP server.
• Courier’s MCP server gives the agent direct access to your workspace, so it can create templates, build journeys, upsert users, and read send logs as it works. See Build with AI for setup in Claude Code, Cursor, Codex, and VS Code.
• Docs for agents. Point it at llms-full.txt when it needs API detail beyond this page.

Help me migrate our notification sending from Intercom to Courier.

Read first:
- https://www.courier.com/docs/tutorials/migrate/from-intercom
  (concept mapping, constraints, and the phased plan you should follow)
- https://www.courier.com/docs/llms-full.txt
  (full Courier docs, for API detail as you need it)

Our setup:
- Codebase: [path]
- Intercom access token: [env var]
- Courier: connected through the Courier MCP server

Work in this order. Stop after step 3 and wait for my review
before you create anything in Courier.

0. Setup. Install Courier Skills so you build against Courier's real
   APIs and patterns rather than guessing:
   npx skills add trycourier/courier-skills
   Then confirm the Courier MCP server is connected. If either one is
   missing, stop and tell me before going further.

1. Inventory. Intercom has no endpoint that lists Series or outbound
   messages, so I will paste in the list from the Outbound screen.
   For each item, record: name, trigger (manual, rule, or event),
   channels, audience, and the event name if it is event-triggered.
   If you need per-message volume, use POST /export/content/data.

2. Classify each item as:
   - transactional (a user action must produce it)
   - marketing (campaign or lifecycle)
   - in-product guidance (banner, tooltip, tour, checklist, carousel)
   The third group does not move to Courier. Flag it and leave it.

3. Find the send sites. Grep the codebase for Intercom POST /events
   and POST /messages calls. For each event call, decide whether it
   exists to trigger a message or only to give support agents context
   in the Intercom Inbox. Only the first group becomes a Courier send.

   Report the inventory, the classification, and the send-site list.
   Then wait.

4. Transactional first. For each transactional item: create the
   Courier template with the channels it needs, then rewrite its call
   site from an Intercom event post to a Courier /send that names the
   template and passes data. Leave the Intercom call in place behind a
   flag so we can run both and compare output.

5. Journeys. Recreate each Series through the Courier journeys API.
   Waits become delay nodes, rules branches become branch nodes,
   messages become send nodes, exit rules become cancel nodes. Where
   the Series depended on our backend precomputing a roll-up, use a
   batch or digest node instead.

Rules:
- Never send to a real user. Use a test profile for every verification send.
- Never pause, unpublish, or delete anything in Intercom. That is my call.
- If an Intercom message relies on something Courier does not have, say so
  in your report rather than approximating it.

​

FAQ