Add AutoRelay to your app in a few calls.

Use a Mail send key with POST https://relay.mlib.app/v1/send.

curl -X POST https://relay.mlib.app/v1/send \
  -H "Authorization: Bearer YOUR_MAIL_SEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "you@example.com",
    "subject": "AutoRelay test",
    "html": "<p>Hello from AutoRelay.</p>",
    "idempotency_key": "app-send-001"
  }'

const response = await fetch("https://relay.mlib.app/v1/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTORELAY_MAIL_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    to: "you@example.com",
    subject: "AutoRelay test",
    html: "<p>Hello from AutoRelay.</p>",
    idempotency_key: `app-${Date.now()}`
  })
});

const data = await response.json();
console.log(data);

Required fields

• to for the recipient address
• subject for the message subject
• html for the rendered body
• idempotency_key to prevent duplicate sends

Use an Events key with POST https://relay.mlib.app/v1/events.

curl -X POST https://relay.mlib.app/v1/events \
  -H "Authorization: Bearer YOUR_EVENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "user_signed_up",
    "user_id": "user_123",
    "properties": {
      "email": "you@example.com"
    }
  }'

const response = await fetch("https://relay.mlib.app/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTORELAY_EVENTS_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    event_name: "user_signed_up",
    user_id: "user_123",
    properties: {
      email: "you@example.com"
    }
  })
});

const data = await response.json();
console.log(data);

Typical event payload

• event_name names the trigger
• user_id identifies the actor or customer
• properties carries flow context like email or plan

Create a flow with an Events key.

curl -X POST https://relay.mlib.app/v1/flows \
  -H "Authorization: Bearer YOUR_EVENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Flow",
    "status": "active",
    "trigger_kind": "event",
    "trigger_value": "user_signed_up",
    "audience_filter": "",
    "steps": [
      {
        "id": "step_send_welcome",
        "type": "send_email",
        "label": "Welcome message",
        "config": {
          "mode": "inline",
          "subject": "Welcome",
          "html": "<p>Thanks for joining.</p>"
        }
      }
    ]
  }'

curl -X GET https://relay.mlib.app/v1/flows \
  -H "Authorization: Bearer YOUR_EVENTS_KEY"

Execution model

• Create or update the flow through /v1/flows.
• Trigger it by sending an event to /v1/events.
• Keep the flow active and scoped to the project tied to your events key.
• Flow email steps use the project sender domain and default sender email when branded sending is configured.
• Read the guides mini blog for fuller examples and Flow Studio use cases.

POST /v1/flows response

{
  "id": "flow_uuid",
  "project_id": "proj_123",
  "name": "Welcome Flow",
  "status": "active",
  "version": 1,
  "updated_at": "2026-03-22T23:32:43.780282+00:00",
  "definition": {
    "entry": {
      "kind": "event",
      "value": "user_signed_up",
      "audience_filter": null
    },
    "steps": [
      {
        "id": "step_send_welcome",
        "type": "send_email",
        "label": "Welcome message",
        "config": {
          "mode": "inline",
          "subject": "Welcome",
          "html": "<p>Thanks for joining.</p>"
        }
      }
    ]
  }
}

POST /v1/events response

{
  "event_id": "event_uuid",
  "status": "accepted",
  "flow_result": {
    "matchedFlows": 1,
    "sentMessages": 1,
    "scheduledWaits": 0,
    "emittedSignals": 0
  }
}

The event response confirms flow execution counts. It does not report the sender address used for the email.

Use a project sender domain when you want mail to come from your own brand.

1. Open your project in the dashboard.
2. Enter a sender domain like mail.example.com.
3. Click Save Domain.
4. Copy each CNAME host and target into your DNS provider.
5. If your DNS provider manages the parent zone, use the shorter host value first. Use the full hostname only if your provider requires it.
6. Wait for propagation, then click Refresh.

DNS guidance

• The records shown by AutoRelay are DKIM CNAME records.
• For a sender domain like mail.example.com, many DNS providers want a host like token._domainkey.mail instead of the full hostname.
• If you use Cloudflare, keep them on DNS only.
• Old provider records usually do not conflict unless they use the exact same hostname.
• Once verification completes, the project can send from that domain.

Default behavior

• If a project has a verified sender domain and default sender email, flow email steps use that sender automatically.
• If no branded sender is configured, sends fall back to the shared default sender for the workspace.
• The sender used is not included in the /v1/events response. Check the project sender settings or the delivered message headers when testing.

Normalization note

• You can send audience_filter as an empty string when creating a flow.
• Stored flow definitions may normalize that value to null. That is expected behavior.

Recommended test pattern

• Verify a project sender domain such as mail.northstar.example.
• Set a project default sender email such as noreply@mail.northstar.example.
• Create a one-step flow with a unique event trigger.
• Send the matching event and confirm matchedFlows and sentMessages in the API response.
• Check the delivered email headers or inbox view to confirm the actual sender address.

Why both checks matter

• The API response tells you whether the flow executed.
• The inbox tells you whether branded sender configuration is correct.
• Use both when validating sender setup for a production project.

Event accepted but no flow matched

• Confirm the flow is active.
• Confirm trigger_value matches the exact event_name.
• Confirm the event is sent with the same project-scoped Events key.

Flow matched but no email sent

• Confirm properties.email is present.
• Confirm the send-email step has valid subject and HTML content.
• Confirm the sender domain is verified if you expect branded delivery.

Mail sent from the wrong sender

• Confirm the project sender domain is verified.
• Confirm the project default sender email matches the brand you expect.
• Remember that sender identity is not shown in the /v1/events response.