Report Spam or Not Spam

Tell SpamFoo Client that a user marked a message as spam, or rescued it from junk as not spam. SpamFoo Client learns from the correction for that user and may report it to SpamFoo to improve the global models.

When to Use It

• A user moves a message into the junk folder, or clicks a "Mark as spam" control.
• A user moves a message out of the junk folder, or clicks a "Not spam" control.
• To report that a message belongs in a different Email Classification, use Report a Classification Fix instead.

What SpamFoo Client does with a correction:

• Learns for the user: it stores an embedding of the message (a list of numbers that represents its content, not the text) in the user's correction memory. Later messages from the same sender, or very similar messages, are judged with that correction in mind. See How Personalization Works.
• Keeps a local copy: it saves a compressed copy of the corrected message on the SpamFoo Client server, so the correction can be rebuilt when the embedding model changes.
• Reports model mistakes: when the correction disagrees with what the global models decided, SpamFoo Client queues an anonymized correction for SpamFoo. The user ID is hashed first. It skips the report when the user's own past corrections decided the message, or when the global models already agreed. See How Corrections Are Used.
• Feeds reputation: when SpamFoo Client reports to SpamFoo, the correction also counts toward the reputation of the IP address in X-Sender-IP and, when the message passed DMARC or aligned SPF, the sender's domain.

Send the message the user corrected, as it is stored in their mailbox. 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": "personalization_only",
    "userId": "[email protected]"
}

Send a Correction More Than Once

If your integration can send the same correction 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 correction 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.
• An ID counts as used only after its correction 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 correction is applied, because a user can correct the same message more than once.

Errors

Example

This example reports that a user rescued a message from junk, and that SpamFoo had originally marked it as spam.

curl -X POST http://localhost:16253/feedback-stream \
    -H "Content-Type: message/rfc822" \
    -H "X-SpamFoo-Proxy-Auth: $SPAMFOO_PROXY_SECRET" \
    -H "X-User-ID: [email protected]" \
    -H "X-Is-Spam: false" \
    -H "X-Original-Is-Spam: true" \
    -H "X-Sender-IP: 203.0.113.50" \
    -H "X-Sender-Email: [email protected]" \
    --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, "/feedback-stream") { Content = content };
request.Headers.Add("X-SpamFoo-Proxy-Auth", secret);
request.Headers.Add("X-User-ID", "[email protected]");
request.Headers.Add("X-Is-Spam", "false");
request.Headers.Add("X-Original-Is-Spam", "true");
request.Headers.Add("X-Sender-IP", "203.0.113.50");
request.Headers.Add("X-Sender-Email", "[email protected]");

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-Is-Spam": "false",
    "X-Original-Is-Spam": "true",
    "X-Sender-IP": "203.0.113.50",
    "X-Sender-Email": "[email protected]",
}

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

print(response.status_code, response.text)