A message style is a reusable subject/body template an alert rule renders when it fires -- built from MA: substitution tokens (job name, status, error text, and so on). See the conceptual overview for the token reference; this page is the API mechanics for managing styles themselves.

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

  1. Authenticate to the API.
  2. Write the subject/body templates.
  3. Create, update, or delete the style.

The calls

GET    /api/message-styles
POST   /api/message-styles
PUT    /api/message-styles/{messageStyleId}
GET    /api/message-styles/{messageStyleId}/usage
POST   /api/message-styles/{messageStyleId}/reassign
DELETE /api/message-styles/{messageStyleId}

Permission needed: Credential.View to list or check usage, Credential.Manage for everything else.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Steps 2 & 3: Create a style.
var newStyle = new CreateMessageStyleRequest(StyleName: "Standard Failure", SubjectTemplate: "[FAILED] MA:JobName", BodyTemplate: "MA:JobName failed on MA:ServerName.\n\nError: MA:Error");
var response = await client.PostAsJsonAsync("/api/message-styles", newStyle, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedIdResponse>(jsonOptions);
Console.WriteLine($"Created style id: {created!.Id}");

// List every style.
var styles = await client.GetFromJsonAsync<MessageStyleSummary[]>("/api/message-styles", jsonOptions);
foreach (var s in styles!)
    Console.WriteLine($"{s.MessageStyleId}: {s.StyleName}");

// Update it.
var update = new CreateMessageStyleRequest(StyleName: "Standard Failure", SubjectTemplate: "[FAILED] MA:JobName on MA:ServerName", BodyTemplate: newStyle.BodyTemplate);
var updateResponse = await client.PutAsJsonAsync($"/api/message-styles/{created.Id}", update, jsonOptions);
updateResponse.EnsureSuccessStatusCode();

// Before deleting, check what still uses it, and reassign if needed.
var usage = await client.GetFromJsonAsync<MessageStyleUsageInfo[]>($"/api/message-styles/{created.Id}/usage", jsonOptions);
if (usage!.Length > 0)
{
    var reassign = new ReassignMessageStyleRequest(ToMessageStyleId: 1);
    (await client.PostAsJsonAsync($"/api/message-styles/{created.Id}/reassign", reassign, jsonOptions)).EnsureSuccessStatusCode();
}
(await client.DeleteAsync($"/api/message-styles/{created.Id}")).EnsureSuccessStatusCode();

record CreateMessageStyleRequest(string StyleName, string SubjectTemplate, string BodyTemplate);
record CreatedIdResponse(int Id);
record MessageStyleSummary(int MessageStyleId, string StyleName, string SubjectTemplate, string BodyTemplate);
record MessageStyleUsageInfo(int JobAlertRuleId, int? JobId, int? JobStepId, string Label, byte TriggerOnRunStatusCode, string RunStatusName);
record ReassignMessageStyleRequest(int ToMessageStyleId, int[]? JobAlertRuleIds = null);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Steps 2 & 3: Create a style. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newStyle = @{ StyleName = "Standard Failure"; SubjectTemplate = "[FAILED] MA:JobName"; BodyTemplate = "MA:JobName failed on MA:ServerName.`n`nError: MA:Error" } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/message-styles" `
    -Method Post -Body $newStyle -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Created style id: $($created.id)"

# List every style.
$styles = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/message-styles" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$styles | ForEach-Object { "$($_.messageStyleId): $($_.styleName)" }

# Before deleting, check what still uses it, and reassign if needed.
$usage = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/message-styles/$($created.id)/usage" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
if ($usage.Count -gt 0) {
    $reassign = @{ ToMessageStyleId = 1 } | ConvertTo-Json
    Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/message-styles/$($created.id)/reassign" `
        -Method Post -Body $reassign -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
}
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/message-styles/$($created.id)" -Method Delete -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

What you get back

POST -- 201 Created: { "id": 3 }

GET -- 200 OK, an array of MessageStyleSummary. GET .../usage -- 200 OK, an array of MessageStyleUsageInfo (empty if unused).

PUT/POST .../reassign/DELETE -- 204 No Content -- no body.

Codes this call can return

See API Response Codes for what each one means in general. For these calls:

  • 201 -- created.
  • 200 -- the list or usage check.
  • 204 -- updated, reassigned, or deleted.
  • 400 -- (create/update) a style with that name already exists; (reassign) ToMessageStyleId is the same style you're reassigning from.
  • 403 -- you don't have the required permission.
  • 409 -- (delete) the style is still used by one or more alert rules -- reassign or remove them first.

What gets audited

Create/update/delete/reassign are each recorded as MessageStyle / Create Message Style, Alter Message Style, Delete Message Style, Reassign Alert Rules. The list and usage GETs aren't audited.

See also: Manage Alert Rules, Test an Alert Channel (previews a real style).