Workflow API

Email and SMS reminder

{
  "instanceName": "payment_reminder",
  "records": [
    {
      "primaryReference": "CUST-1042",
      "firstName": "Sam",
      "phoneNumber": "07700900123",
      "emailAddress": "sam@example.com",
      "variables": [
        {
          "name": "balance",
          "value": "345.22"
        },
        {
          "name": "due_date",
          "value": "16/11/2026"
        }
      ]
    }
  ]
}

Request

{
  "records": [
    23997
  ],
  "includeSmsInformation": true,
  "includeEmailInformation": true
}

C#

// Submit a record to an everymessage Workflow instance (.NET 8 or later)
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

var apiKey = Environment.GetEnvironmentVariable("EM_WORKFLOW_KEY")!;
var secretKey = Environment.GetEnvironmentVariable("EM_WORKFLOW_SECRET")!;

using var http = new HttpClient { BaseAddress = new Uri("https://wfa.everymessage.com/rest/v1/") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:{secretKey}")));

var json = new JsonSerializerOptions(JsonSerializerDefaults.Web)
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};

// The instance decides what happens: email, SMS, a voice call, or a sequence of them.
var request = new SubmitRequest(
    InstanceName: "payment_reminder",
    Records:
    [
        new Record(
            PrimaryReference: "CUST-1042",
            FirstName: "Sam",
            PhoneNumber: "07700900123",
            EmailAddress: "sam@example.com",
            Variables: [new("balance", "345.22"), new("due_date", "16/11/2026")])
    ]);

using var response = await http.PostAsJsonAsync("records/submit", request, json);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadFromJsonAsync<Envelope<SubmitBody>>(json)
             ?? throw new InvalidOperationException("Empty response from everymessage");

// The API returns HTTP 200 even on errors: check responseStatusCode in the body.
if (result.ResponseStatusCode != 200)
    throw new InvalidOperationException(
        $"Submit failed: {result.ResponseStatusReason} {result.ResponseStatusMessage}");

// Keep workflowRecordId: it is how you query the record later.
foreach (var r in result.Body!.Records)
    Console.WriteLine($"{r.PrimaryReference}: workflow record {r.WorkflowRecordId}");

Console.WriteLine($"{result.Body.RecordsSubmitted} submitted, {result.Body.RecordsWithWarningFlag} with warnings");

record SubmitRequest(string InstanceName, IReadOnlyList<Record> Records,
    string? BatchName = null, bool DeletePendingRecords = false);
record Record(string PrimaryReference, string? FirstName = null, string? Surname = null,
    string? PhoneNumber = null, string? EmailAddress = null, DateTime? ScheduledRun = null,
    IReadOnlyList<Variable>? Variables = null);
record Variable(string Name, string Value);

record Envelope<T>(int ResponseStatusCode, string? ResponseStatusReason,
    string? ResponseStatusMessage, T? Body);
record SubmitBody(IReadOnlyList<SubmittedRecord> Records, int RecordsSubmitted, int RecordsWithWarningFlag);
record SubmittedRecord(string PrimaryReference, long WorkflowRecordId);

C#

// Check the progress of Workflow records, with the SMS and email they sent (.NET 8 or later)
// Usage: dotnet run -- <workflowRecordId> [<workflowRecordId> ...]
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

var apiKey = Environment.GetEnvironmentVariable("EM_WORKFLOW_KEY")!;
var secretKey = Environment.GetEnvironmentVariable("EM_WORKFLOW_SECRET")!;

using var http = new HttpClient { BaseAddress = new Uri("https://wfa.everymessage.com/rest/v1/") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:{secretKey}")));

var json = new JsonSerializerOptions(JsonSerializerDefaults.Web)
{
    NumberHandling = JsonNumberHandling.AllowReadingFromString   // ids may arrive as "23996"
};

var query = new { records = args.Select(long.Parse).ToArray(), includeSmsInformation = true, includeEmailInformation = true };

using var response = await http.PostAsJsonAsync("records/query", query, json);
response.EnsureSuccessStatusCode();

var result = await response.Content.ReadFromJsonAsync<Envelope<QueryBody>>(json)
             ?? throw new InvalidOperationException("Empty response from everymessage");

if (result.ResponseStatusCode != 200)
    throw new InvalidOperationException(
        $"Query failed: {result.ResponseStatusReason} {result.ResponseStatusMessage}");

foreach (var r in result.Body!.Records)
{
    Console.WriteLine($"Record {r.DataReference} ({r.PrimaryReference}): {r.ProcessingStatus}");
    foreach (var s in r.SentSmsMessages ?? [])
        Console.WriteLine($"  SMS {s.Reference}: sent {s.Sent}, delivered {s.Delivered?.ToString() ?? "awaiting receipt"}");
    foreach (var e in r.SentEmailDocuments ?? [])
        Console.WriteLine($"  Email to {string.Join(", ", e.To ?? [])}: sent {e.Sent?.ToString() ?? "unknown"}" +
            (e.DeliveryFailure == true ? $", failed: {e.DeliveryFailureMessage}" : ""));
}

record Envelope<T>(int ResponseStatusCode, string? ResponseStatusReason,
    string? ResponseStatusMessage, T? Body);
record QueryBody(IReadOnlyList<WorkflowRecord> Records);
record WorkflowRecord(long DataReference, string? PrimaryReference, string ProcessingStatus,
    IReadOnlyList<SentSms>? SentSmsMessages, IReadOnlyList<SentEmail>? SentEmailDocuments);
record SentSms(string? Reference, bool Sent, DateTime? SentDate, bool? Delivered,
    int? DeliveryCode, DateTime? DeliveryDate);
record SentEmail(string? Reference, string? From, IReadOnlyList<string>? To, bool? Sent,
    bool? DeliveryFailure, string? DeliveryFailureMessage);