Close the email loop: inbound parse, Flow reply, ticket

The outbound quickstart ends at a delivered message, and the inbound-routing guide ends at a parsed webhook. This tutorial stitches them into the loop a support address actually needs: a customer writes in, Orbit parses the mail on a managed route, a Flow sends an acknowledgement within seconds, and the thread opens as a ticket in the inbox for an agent to pick up. The SDK tabs below read the API key from ORBIT_API_KEY; cURL passes it as X-API-Key. Where a route sits below an SDK’s typed helpers, the tab uses that SDK’s escape hatch — orbit.request (Node.js), client.request (Python and Ruby), client.Request (Go), $client->request (PHP) — the same convention the Sandbox API cookbook uses for untyped routes, per the SDK sample coverage policy. You will:

See the loop you are about to build
Baseline the outbound send
Provision a receiving domain
Register the inbound route
Handle the inbound event with a Flow
Read the thread as a ticket in the Inbox
Debug the common failure modes

1. What you build

One work loop, end to end:

An outbound send establishes your verified sender and domain (two lines of cURL — the full sender verification is in Send your first transactional email).
An inbound route rents an address the customer can write back to.
A Flow reacts to the inbound event and replies “we got your message” without an agent touching anything.
The same inbound mail opens a ticket in the Inbox, so an agent owns the follow-up.

2. Outbound baseline

Confirm the sender exists and mail goes out — this is the whole outbound side of the loop:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/email \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "self@your-domain.com",
    "subject": "Outbound baseline",
    "html": "<p>Loop step 1.</p>"
  }'

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// resolves on 202; any non-2xx answer throws a typed error
const sent = await orbit.messages.sendEmail({
  to: 'self@your-domain.com',
  subject: 'Outbound baseline',
  html: '<p>Loop step 1.</p>',
});
console.log(sent.data.succeeded); // non-empty = move on

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request(
    "POST",
    "/messages/email",
    json={
        "to": "self@your-domain.com",
        "subject": "Outbound baseline",
        "html": "<p>Loop step 1.</p>",
    },
)  # 202 accepted
print(res["data"]["succeeded"])  # non-empty = move on

var sent map[string]any
err := client.Request(context.Background(), "POST", "/messages/email", nil, map[string]any{
    "to":      "self@your-domain.com",
    "subject": "Outbound baseline",
    "html":    "<p>Loop step 1.</p>",
}, &sent, "")
// 202 accepted; sent["data"].(map[string]any)["succeeded"] non-empty = move on
_ = err

sent = client.request("POST", "/messages/email", json_body: {
  to: "self@your-domain.com",
  subject: "Outbound baseline",
  html: "<p>Loop step 1.</p>",
}) # 202 accepted
puts sent.dig("data", "succeeded") # non-empty = move on

$sent = $client->request('POST', '/messages/email', null, [
    'to' => 'self@your-domain.com',
    'subject' => 'Outbound baseline',
    'html' => '<p>Loop step 1.</p>',
]); // 202 accepted
var_dump($sent['data']['succeeded']); // non-empty = move on

A 202 with data.succeeded non-empty is the signal to move on. Work through Send your first transactional email first if any of domain verification, sender registration, or template rendering is still open — the inbound steps below assume that path is green.

3. Provision the receiving domain

Pick a dedicated subdomain (for example inbound.your-domain.com) so MX routing for inbound parse does not compete with your corporate mail, and point its MX records at Orbit’s ingress — the dashboard shows the hostname under Email → Inbound routes → Add route. Any address at that domain becomes a candidate for a route once DNS propagates. This is the same flow as step 1 of Inbound email and SMS routing.

4. Register the inbound route

curl -X POST https://api.orbit.devotel.io/api/v1/email/inbound-routes \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipientPattern": "support@inbound.your-domain.com",
    "destinationUrl": "https://api.your-app.com/hooks/orbit-inbound",
    "includeRawMime": false,
    "description": "Support loop → ack Flow + inbox ticket"
  }'

const route = await orbit.request('POST', '/email/inbound-routes', {
  recipientPattern: 'support@inbound.your-domain.com',
  destinationUrl: 'https://api.your-app.com/hooks/orbit-inbound',
  includeRawMime: false,
  description: 'Support loop → ack Flow + inbox ticket',
});
// 201 — route.data.signingSecret returns exactly once; store it now

route = client.request(
    "POST",
    "/email/inbound-routes",
    json={
        "recipientPattern": "support@inbound.your-domain.com",
        "destinationUrl": "https://api.your-app.com/hooks/orbit-inbound",
        "includeRawMime": False,
        "description": "Support loop → ack Flow + inbox ticket",
    },
)  # 201
# route["data"]["signingSecret"] returns exactly once; store it now

var route map[string]any
err := client.Request(context.Background(), "POST", "/email/inbound-routes", nil, map[string]any{
    "recipientPattern": "support@inbound.your-domain.com",
    "destinationUrl":   "https://api.your-app.com/hooks/orbit-inbound",
    "includeRawMime":   false,
    "description":      "Support loop → ack Flow + inbox ticket",
}, &route, "")
// 201 — route["data"].(map[string]any)["signingSecret"] returns exactly once; store it now
_ = err

route = client.request("POST", "/email/inbound-routes", json_body: {
  recipientPattern: "support@inbound.your-domain.com",
  destinationUrl: "https://api.your-app.com/hooks/orbit-inbound",
  includeRawMime: false,
  description: "Support loop → ack Flow + inbox ticket",
}) # 201
puts route.dig("data", "signingSecret") # returns exactly once; store it now

$route = $client->request('POST', '/email/inbound-routes', null, [
    'recipientPattern' => 'support@inbound.your-domain.com',
    'destinationUrl' => 'https://api.your-app.com/hooks/orbit-inbound',
    'includeRawMime' => false,
    'description' => 'Support loop → ack Flow + inbox ticket',
]); // 201
// $route['data']['signingSecret'] returns exactly once; store it now

The 201 response carries the route’s signingSecret exactly once — store it now, because list and get responses mask it:

{
  "data": {
    "id": "einr_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "recipientPattern": "support@inbound.your-domain.com",
    "destinationUrl": "https://api.your-app.com/hooks/orbit-inbound",
    "signingSecret": "einrsk_c0ffee…",
    "active": true
  }
}

Verify X-Orbit-Signature (sha256=<hex> HMAC over the raw request body) on every forward — the full receiver pattern is in Build a durable webhook consumer. A lightweight receiver that verifies and returns 2xx quickly is all this step needs.

5. Handle the inbound event with a Flow

Inbound email route rules have no reply path themselves — the constraint is stated verbatim in the inbound-routing guide, and a Flow is its designated resolve. Subscribe to the inbound message.received event and compose the acknowledgement:

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support auto-ack",
    "trigger_type": "event",
    "definition": {
      "trigger": {
        "type": "event",
        "event": "message.received",
        "filters": { "channel": "email" }
      },
      "nodes": [
        {
          "id": "ack",
          "type": "sendEmail",
          "data": {
            "to": "{{from}}",
            "subject": "Re: {{subject}}",
            "body": "Thanks — ticket {{ticket_id}} opened. An agent will pick this up shortly."
          }
        }
      ],
      "edges": []
    }
  }'

const flow = await orbit.flows.create({
  name: 'Support auto-ack',
  trigger_type: 'event',
  definition: {
    trigger: {
      type: 'event',
      event: 'message.received',
      filters: { channel: 'email' },
    },
    nodes: [
      {
        id: 'ack',
        type: 'sendEmail',
        data: {
          to: '{{from}}',
          subject: 'Re: {{subject}}',
          body: 'Thanks — ticket {{ticket_id}} opened. An agent will pick this up shortly.',
        },
      },
    ],
    edges: [],
  },
});
console.log(flow.data.id); // the ack Flow is live

flow = client.request(
    "POST",
    "/flows",
    json={
        "name": "Support auto-ack",
        "trigger_type": "event",
        "definition": {
            "trigger": {
                "type": "event",
                "event": "message.received",
                "filters": {"channel": "email"},
            },
            "nodes": [
                {
                    "id": "ack",
                    "type": "sendEmail",
                    "data": {
                        "to": "{{from}}",
                        "subject": "Re: {{subject}}",
                        "body": "Thanks — ticket {{ticket_id}} opened. An agent will pick this up shortly.",
                    },
                }
            ],
            "edges": [],
        },
    },
)
print(flow["data"]["id"])  # the ack Flow is live

var flow map[string]any
err := client.Request(context.Background(), "POST", "/flows", nil, map[string]any{
    "name":           "Support auto-ack",
    "trigger_type":   "event",
    "definition": map[string]any{
        "trigger": map[string]any{
            "type":    "event",
            "event":   "message.received",
            "filters": map[string]any{"channel": "email"},
        },
        "nodes": []map[string]any{
            {
                "id":   "ack",
                "type": "sendEmail",
                "data": map[string]any{
                    "to":      "{{from}}",
                    "subject": "Re: {{subject}}",
                    "body":    "Thanks — ticket {{ticket_id}} opened. An agent will pick this up shortly.",
                },
            },
        },
        "edges": []map[string]any{},
    },
}, &flow, "")
// flow["data"].(map[string]any)["id"] — the ack Flow is live
_ = err

flow = client.request("POST", "/flows", json_body: {
  name: "Support auto-ack",
  trigger_type: "event",
  definition: {
    trigger: { type: "event", event: "message.received", filters: { channel: "email" } },
    nodes: [
      {
        id: "ack",
        type: "sendEmail",
        data: {
          to: "{{from}}",
          subject: "Re: {{subject}}",
          body: "Thanks — ticket {{ticket_id}} opened. An agent will pick this up shortly.",
        },
      },
    ],
    edges: [],
  },
})
puts flow.dig("data", "id") # the ack Flow is live

$flow = $client->request('POST', '/flows', null, [
    'name' => 'Support auto-ack',
    'trigger_type' => 'event',
    'definition' => [
        'trigger' => ['type' => 'event', 'event' => 'message.received', 'filters' => ['channel' => 'email']],
        'nodes' => [
            [
                'id' => 'ack',
                'type' => 'sendEmail',
                'data' => [
                    'to' => '{{from}}',
                    'subject' => 'Re: {{subject}}',
                    'body' => 'Thanks — ticket {{ticket_id}} opened. An agent will pick this up shortly.',
                ],
            ],
        ],
        'edges' => [],
    ],
]);
var_dump($flow['data']['id']); // the ack Flow is live

The channel: "email" filter prevents the ack Flow from answering SMS and WhatsApp inbound too. This minimal form — event trigger, one send node — is the whole loop; the Flows overview covers branches, delays, and richer orchestration. The inbound event the Flow’s {{from}} and {{subject}} templates read is the same envelope your destinationUrl receives on every forward:

{
  "event": "message.received",
  "data": {
    "id": "msg_in_7c21e0aa9b3d",
    "channel": "email",
    "from": "customer@example.com",
    "to": "support@inbound.your-domain.com",
    "subject": "Question about my order"
  }
}

6. The thread lands in the Inbox

Every matched inbound email opens (or threads onto) an inbox ticket in parallel with the webhook forward — your Flow acknowledgement fires off the pipeline while an agent picks up the assigned work under Inbox. The ticket fields and the receive → reply pattern at the API level are in Send & Receive Messages. Keep the Flow reply short and factual; the agent reads the ticket and carries the conversation from there.

7. Common failures

Route never fires. recipientPattern is matched against the SMTP envelope recipient first, then the To and Cc headers — but only when one of them names the address you registered. BCC-only mail, and mail whose envelope was rewritten upstream, both miss. Log the recipient your sending path actually used and match that — full matching rules are in Inbound email and SMS routing.
Signature mismatch. X-Orbit-Signature is HMAC over the raw request body — verifying a re-serialized JSON body always fails. Read the body as bytes before any framework middleware parses it; the pattern is in Build a durable webhook consumer.
Duplicate route rejected. Registering the same recipientPattern twice returns 409 CONFLICT on the second call — update the existing route with PATCH instead of re-creating it.
Flow fires for every channel. The filters.channel field scopes the trigger — omit it and your ack reply answers SMS and WhatsApp inbound too.
Ticket never opens on a broken webhook. The ticket pipeline runs in parallel with webhook forward — but only if a route actually matched. If GET /email/inbound-routes shows rising failureCount, the match may still be firing; if lastFailureAt is empty and no ticket opens, re-check the pattern from the bullets above.

WhatsApp

Developer console

Contact center

Guides

Admin

Messaging Controls

Audience & Support Tools

Close the email loop: inbound parse, Flow reply, ticket

Close the email loop: inbound parse, Flow reply, ticket

1. What you build

2. Outbound baseline

3. Provision the receiving domain

4. Register the inbound route

5. Handle the inbound event with a Flow

6. The thread lands in the Inbox

7. Common failures

​Close the email loop: inbound parse, Flow reply, ticket

​1. What you build

​2. Outbound baseline

​3. Provision the receiving domain

​4. Register the inbound route

​5. Handle the inbound event with a Flow

​6. The thread lands in the Inbox

​7. Common failures

Close the email loop: inbound parse, Flow reply, ticket

1. What you build

2. Outbound baseline

3. Provision the receiving domain

4. Register the inbound route

5. Handle the inbound event with a Flow

6. The thread lands in the Inbox

7. Common failures