Report a Classification Fix

Tell SpamFoo Client that a user moved a message to a different Email Classification, for example from Promotions to Primary. SpamFoo Client learns from the fix for that user and may report it to SpamFoo to improve the global model.

When to Use It

• A user drags a message to another classification tab or folder.
• A user picks a new classification for a message from a menu.
• To report spam or not spam, use Report Spam or Not Spam instead.

What SpamFoo Client does with a fix:

• Learns for the user: it stores an embedding of the message (a list of numbers that represents its content) with the new classification in the user's classification memory. Later messages from the same sender, or very similar messages, can get that classification. See How Personalization Works.
• Keeps a local copy: it saves a compressed copy of the message on the SpamFoo Client server, so the fix can be rebuilt when the embedding model changes.
• Reports model mistakes: when the new classification differs from the original one, SpamFoo Client queues an anonymized correction for SpamFoo. The user ID is hashed first. It skips the report when the original and new classifications match, or when the user's own past fixes decided the original classification. See How Corrections Are Used.

The message must have a From address, because SpamFoo Client links the fix to the sender. This endpoint has no license check.

Request

The body is the raw message (raw .eml content), sent unchanged. See Send the Message in the Request Body.

Response

A successful request returns 200:

{
    "status": "success",
    "userId": "[email protected]",
    "classification": "primary"
}

Send a Fix More Than Once

If your integration can send the same fix twice, such as a retry after a lost answer, add X-SpamFoo-Event-Id with an ID that stays the same across retries.

• The ID is 1 to 128 printable ASCII characters with no spaces. An ID that doesn't fit is ignored, and the fix is applied normally.
• A repeat of an ID that was already applied for the same user on this endpoint returns 200 with {"status": "duplicate", "duplicate": true, "userId": "[email protected]"} and changes nothing. That answer has no classification field.
• An ID counts as used only after its fix succeeds, so you can retry a failed attempt with the same ID.
• SpamFoo Client remembers IDs in memory for 24 hours. A restart forgets them.
• Without the header, every fix is applied, because a user can fix the same message more than once.

Errors

Example

This example reports that a user moved a message from Promotions to Primary.

curl -X POST http://localhost:16253/tabs/feedback-stream \
    -H "Content-Type: message/rfc822" \
    -H "X-SpamFoo-Proxy-Auth: $SPAMFOO_PROXY_SECRET" \
    -H "X-User-ID: [email protected]" \
    -H "X-Classification: primary" \
    -H "X-Original-Classification: promotions" \
    --data-binary @message.eml

using System.Net.Http.Headers;

var secret = Environment.GetEnvironmentVariable("SPAMFOO_PROXY_SECRET")
    ?? throw new InvalidOperationException("Set SPAMFOO_PROXY_SECRET.");

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:16253") };

await using var eml = File.OpenRead("message.eml");
var content = new StreamContent(eml);
content.Headers.ContentType = new MediaTypeHeaderValue("message/rfc822");

using var request = new HttpRequestMessage(HttpMethod.Post, "/tabs/feedback-stream") { Content = content };
request.Headers.Add("X-SpamFoo-Proxy-Auth", secret);
request.Headers.Add("X-User-ID", "[email protected]");
request.Headers.Add("X-Classification", "primary");
request.Headers.Add("X-Original-Classification", "promotions");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

import os

import requests

headers = {
    "Content-Type": "message/rfc822",
    "X-SpamFoo-Proxy-Auth": os.environ["SPAMFOO_PROXY_SECRET"],
    "X-User-ID": "[email protected]",
    "X-Classification": "primary",
    "X-Original-Classification": "promotions",
}

with open("message.eml", "rb") as eml:
    response = requests.post(
        "http://localhost:16253/tabs/feedback-stream",
        data=eml,
        headers=headers,
        timeout=60,
    )

print(response.status_code, response.text)