Misar.Reach 5.0.3

MisarReach .NET SDK

Async .NET client for MisarReach — find leads, enrich and verify them, then work them through a CRM pipeline and multi-channel outreach.

17 resource groups · 94 operations

Targets net8.0 with no third-party dependencies — System.Text.Json and HttpClient only. Every call is async and returns a JsonElement. Unlike the other SDKs the surface is flat: there are no resource sub-objects, just Group_MethodAsync members on MisarReachClient. Talks to https://api.misar.io/reach/api.

Install

dotnet add package Misar.Reach --version 5.0.3

Or in your .csproj:

<ItemGroup>
  <PackageReference Include="Misar.Reach" Version="5.0.3" />
</ItemGroup>

Targets net8.0. No third-party dependencies — System.Text.Json and HttpClient only.

Authentication

Create a key in Settings → API keys in the MisarReach app. Reach keys start with mrk_ and are validated against the reach-owned key table only, so a key from another Misar product is rejected. It travels as Authorization: Bearer mrk_….

using Misar.Reach;

using var reach = new MisarReachClient(
    Environment.GetEnvironmentVariable("MISARREACH_API_KEY")!);

MisarReachClient is IDisposable; dispose it (or using it) so the HttpClient it owns is released. Pass your own HttpClient — from IHttpClientFactory, say — and it will not be disposed for you.

Quick start

using Misar.Reach;

using var reach = new MisarReachClient(Environment.GetEnvironmentVariable("MISARREACH_API_KEY")!);

var job = await reach.Leads_SearchAsync(new { query = "CTOs at Series A fintech", useAI = true });
string jobId = job.GetProperty("jobId").GetString()!;

var snapshot = await reach.Leads_JobStatusAsync(jobId);
Console.WriteLine($"{snapshot.GetProperty("job").GetProperty("status").GetString()} " +
                  $"{snapshot.GetProperty("results").GetArrayLength()}");

To point at the app origin, cap retries differently, or supply your own HttpClient (from IHttpClientFactory, say — the client will not dispose one it did not create):

using var pooled = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };

using var pinned = new MisarReachClient(
    apiKey: "mrk_your_key",
    baseUrl: "https://reach.misar.io/api",
    maxRetries: 5,
    httpClient: pooled);

What's in the package

• MisarReachClient — one sealed class, IDisposable, in namespace Misar.Reach. Constructed as new MisarReachClient(apiKey, baseUrl = "https://api.misar.io/reach/api", maxRetries = 3, httpClient = null). Pass your own HttpClient (from IHttpClientFactory, say) and the client will not dispose it; leave it null and the client owns one with a 30-second timeout. A blank apiKey throws ArgumentException at construction.
• No resource classes. Unlike the TypeScript, Python, PHP and Rust SDKs, nothing hangs off the client as a sub-object: all 94 methods sit directly on MisarReachClient, named Area_OperationAsync across 17 area prefixes (Leads_, Contacts_, Deals_, Pipeline_, Campaigns_, CampaignTemplates_, Channels_, Conversations_, SalesAgent_, Autopilot_, Deliverability_, Notifications_, Webhooks_, Workspaces_, Settings_, Ads_, Plan_). That is one method per operation in openapi/reach.openapi.json, so coverage is complete. Type client.Leads_ and let IntelliSense filter — the prefix is the discovery mechanism a resource object would otherwise provide.
• No typed models. Request bodies are plain object — pass an anonymous object and it is serialised with System.Text.Json. Responses are JsonElement, read with GetProperty(...). There is no Lead, Deal or PlanResponse record here, unlike the TypeScript and Python SDKs; the trade is that the open-shape parts of the API never need an SDK release to reach you. Deserialise into your own records with element.Deserialize<T>() if you want static types.
• Query strings are raw strings. Methods that accept filters take a single string? queryParams appended after ? — Leads_ListAsync("page=1&limit=50"). Build it yourself, and Uri.EscapeDataString any user-supplied value.
• MisarReachStreamEvent — a readonly record struct with Event (string), Data (JsonElement) and Raw (string).
• Errors — MisarReachException and the typed subclasses below.
• Transport — HttpClient with a Bearer header, and automatic retries with exponential back-off starting at 500 ms on 429/500/502/503/504 (maxRetries, default 3, exposed as MaxRetries). A plan refusal is not retried: the retry loop parses the body and skips anything carrying upgrade: true, so a 429 rate limit and a 429 plan cap are told apart despite sharing a status.
• SSE streaming for lead-finder job progress, via a callback, not IAsyncEnumerable<T>: Leads_StreamJobAsync(jobId, ev => …, ct) returns a Task that completes when the stream ends. The server sends named events — progress, found, complete, error, timeout — plus a : keepalive comment every 20 seconds, which the parser skips. There is no [DONE] sentinel; the task simply completes when the server closes the stream. A job that has already finished is answered with a JSON snapshot rather than a stream, and the SDK delivers the terminal complete/error event in its place, so a caller that assumed a stream does not hang on nothing. Streams are never retried.

Resources

Every public method, grouped the way the client groups them.

Lead finder

23-source search, enrichment, verification, scoring, lists and the SSE job stream.

Deals

CRM deals, their activity log and AI next steps.

Pipeline

The Kanban board and stage moves.

Campaigns

Multi-step sequences and recipient dispatch.

Campaign templates

Reusable starting points.

Contacts

The audience behind outreach.

Conversations

The unified inbox.

Channels

Connectors, consent links and per-channel health.

AI sales agent

Config, today's actions, and running the agent over a thread.

Autopilot

Goal-driven runs.

Deliverability

Sender reputation.

Notifications

The in-app bell.

Webhooks

Signed outbound endpoints.

Workspaces

Teams and membership.

Plan

Caps and usage.

Settings

Compliance settings.

Ads

Paid-audience export.

Usage

Find leads

Leads_SearchAsync() returns a job id, not leads — the search runs asynchronously and answers 202.

var search = await reach.Leads_SearchAsync(new
{
    query = "heads of ops at logistics startups",
    useAI = true,
    filters = new { location = "Berlin", companySize = "11-50" },
});
string searchJobId = search.GetProperty("jobId").GetString()!;

Stream job progress

using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));

await reach.Leads_StreamJobAsync(searchJobId, ev =>
{
    switch (ev.Event)
    {
        case "progress":
            Console.WriteLine($"working {ev.Data.GetProperty("message").GetString()}");
            break;
        case "found":
            Console.WriteLine($"hit {ev.Data.GetProperty("email").GetString()}");
            break;
        case "complete":
            Console.WriteLine($"done {ev.Data.GetProperty("total_found").GetInt32()}");
            break;
        case "error":
        case "timeout":
            Console.Error.WriteLine($"{ev.Event} {ev.Raw}");
            break;
    }
    return Task.CompletedTask;
}, cts.Token);

The callback is Func<MisarReachStreamEvent, Task>, so a synchronous body ends in return Task.CompletedTask;. Pass a CancellationToken — without one, a stuck job holds the connection open for as long as the server allows.

List saved leads

var page = await reach.Leads_ListAsync("page=1&limit=50");
Console.WriteLine(page.GetProperty("total").GetInt32());

Create a CRM contact and a deal

await reach.Contacts_CreateAsync(new
{
    email = "cto@acme.com",
    firstName = "Dana",
    status = "subscribed",
    consent = new
    {
        source = "signup form /pricing",
        timestamp = DateTime.UtcNow.ToString("o"),
    },
});

var created = await reach.Deals_CreateAsync(new
{
    leadEmail = "cto@acme.com",   // the only required field
    leadName = "Dana Reyes",
    value = 12000,
    currency = "USD",
});
string dealId = created.GetProperty("deal").GetProperty("id").GetString()!;

Read and move the pipeline

var pipeline = await reach.Pipeline_GetAsync();
Console.WriteLine($"{pipeline.GetProperty("stages").GetArrayLength()} stages, " +
                  $"{pipeline.GetProperty("revenue").GetProperty("pipeline").GetInt32()} in open pipeline");

// POST /pipeline is the stage move, despite `Create` in the name.
var moved = await reach.Pipeline_CreateAsync(new { dealId, newStage = "meeting" });

Run a campaign

Steps are ordered by their position in the array — the index becomes step_order, so there is no step_order field to set. channel is the only required key on a step; subject and body sit directly on it, not inside a nested template object.

var campaign = await reach.Campaigns_CreateAsync(new
{
    name = "Q3 fintech outbound",
    steps = new object[]
    {
        new { channel = "email", subject = "Quick question", body = "Hi {{name}} …" },
        new { channel = "email", delay_hours = 72, body = "Following up …" },
    },
});
string campaignId = campaign.GetProperty("id").GetString()!;

var result = await reach.Campaigns_EnqueueAsync(campaignId, new
{
    recipients = new object[]
    {
        new { email = "cto@acme.com", name = "Dana Reyes", company = "Acme" },
    },
});

// Check `warnings`: a step whose channel has no inbound path in this deployment
// can never deliver, and the server reports that here rather than silently
// dropping every recipient at dispatch time.
Console.WriteLine($"{result.GetProperty("queued").GetInt32()} queued, " +
                  $"{result.GetProperty("skipped").GetInt32()} skipped");
if (result.TryGetProperty("warnings", out var warnings))
    foreach (var w in warnings.EnumerateArray())
        Console.WriteLine($"warning: {w}");

Check the plan before an expensive run

using System.Text.Json;

var plan = await reach.Plan_GetAsync();
var searches = plan.GetProperty("usage").GetProperty("lead_searches");

if (searches.GetProperty("remaining").ValueKind == JsonValueKind.Null)
{
    Console.WriteLine($"unlimited lead searches on {plan.GetProperty("plan").GetProperty("name").GetString()}");
}
else if (searches.GetProperty("remaining").GetInt32() == 0)
{
    var offer = plan.GetProperty("upgrade");
    Console.WriteLine($"no searches left; upgrade at {offer.GetProperty("url").GetString()}");
}

usage is keyed by lead_searches, lead_results, autopilot_runs, pipeline_deals and linkedin_seats. upgrade is null until at least one cap is spent, so check its ValueKind before reading url.

Reply into a conversation

var inbox = await reach.Conversations_ListAsync("limit=25");

await reach.Conversations_ReplyAsync("cto@acme.com", new
{
    message = "Happy to walk you through it — does Thursday work?",
});

The body field is message (required, 1–5000 chars); add conversationId to pick a thread other than the contact's most recent. The channel is the thread's, not yours to choose. The email is URL-escaped into the path for you.

Errors

Every non-2xx throws a MisarReachException or one of its subclasses. All live in the Misar.Reach namespace and carry Status and Code.

The same mapping applies to the SSE stream, so a plan refusal on Leads_StreamJobAsync() throws the same typed exception rather than a bare one.

The 402 upgrade case

A counted plan cap answers 402 with upgrade: true — not 403, and not 429. Retrying cannot help until the cap resets or the plan changes, so the retry loop skips it and the exception surfaces immediately:

try
{
    await reach.Leads_SearchAsync(new { query = "…" });
}
catch (UpgradeRequiredException err)
{
    // e.g. feature "lead_searches", current 50 of limit 50
    Console.Error.WriteLine($"{err.Feature}: {err.Current}/{err.Limit}");
    Console.Error.WriteLine($"upgrade at {err.UpgradeUrl}");  // resolved to an absolute URL
}

429 is still accepted as an upgrade refusal when upgrade: true is present, for older deployments — err.Status tells you which you got. This is distinct from the 503 retry: true the server sends when it could not check the quota: that body carries no upgrade flag, so it is retried, and "we don't know" is never mistaken for "you're over your limit".

Reading remaining

In Plan_GetAsync(), a usage entry's limit is null when the plan is unlimited for that counter, and remaining is null alongside it — deliberately not 0, which would read as exhausted. JsonElement.GetInt32() throws on a JSON null, so test ValueKind == JsonValueKind.Null before comparing.

Compliance

Outreach is not uniformly permitted. Email is the only cold-capable channel; SMS and WhatsApp require a consent record, and several social channels may only reply inside a window the recipient opened. The API enforces this server-side and will refuse a send rather than let you breach TCPA, CASL or GDPR — a refusal is the SDK working correctly, not an error to retry around. Sends are also blocked until a CAN-SPAM sender postal address is set via Settings_SetSenderAddressAsync().

Links

• Website — https://www.misarreach.com
• App — https://reach.misar.io
• Parent — https://misar.io
• Documentation — https://docs.misar.io/reach
• Source — https://github.com/Misar-AI/misarreach-sdks
• NuGet — https://www.nuget.org/packages/Misar.Reach

MIT © Misar AI