Corrections API

The corrections endpoints let you submit feedback when a user corrects a misclassification. SpamFoo uses this feedback to improve per-user personalization and global model accuracy. See Feedback & Training for how corrections are processed.

POST /feedback

Coming soon: Submitting feedback by file path is not available yet. Use POST /feedback-stream below to submit a correction by streaming the raw message content.

Submit a spam or ham correction by file path.

Request

POST /feedback
Content-Type: application/json

{
    "path": "/var/spool/mail/message.eml",
    "userId": "user@domain.com",
    "isSpam": true,
    "ipAddress": "203.0.113.50",
    "senderEmail": "sender@example.com"
}

Field	Required	Description
`path`	Yes	Absolute path to the `.eml` file
`userId`	Yes	User who made the correction
`isSpam`	Yes	`true` if the user marked the message as spam, `false` if the user marked it as not spam
`ipAddress`	No	Sender IP address
`senderEmail`	No	Sender email address

Response

{
    "status": "personalization_only",
    "userId": "user@domain.com"
}

POST /feedback-stream

Submit a spam or ham correction by streaming the raw email content.

Request

POST /feedback-stream
Content-Type: message/rfc822
X-User-ID: user@domain.com
X-Is-Spam: true
X-Sender-IP: 203.0.113.50
X-Sender-Email: sender@example.com

[raw .eml content]

Header	Required	Description
`X-User-ID`	Yes	User who made the correction
`X-Is-Spam`	Yes	`true` or `false`
`X-Sender-IP`	No	Sender IP address
`X-Sender-Email`	No	Sender email address
`X-Skip-Rule-Creation`	No	Set to `true` to prevent automatic sender rule creation from this correction

Response format is the same as /feedback.

POST /tabs/feedback

Coming soon: Submitting feedback by file path is not available yet. Use POST /tabs/feedback-stream below to submit a correction by streaming the raw message content.

Submit a tab classification correction by file path.

Request

POST /tabs/feedback
Content-Type: application/json

{
    "path": "/var/spool/mail/message.eml",
    "userId": "user@domain.com",
    "correctClassification": "updates"
}

Field	Required	Description
`path`	Yes	Absolute path to the `.eml` file
`userId`	Yes	User who made the correction
`correctClassification`	Yes	The correct classification: `primary`, `promotions`, `updates`, `transactions`, or `automatic` (to reset to model default)

Response

{
    "status": "success",
    "userId": "user@domain.com",
    "classification": "updates"
}

POST /tabs/feedback-stream

Submit a tab correction by streaming the raw email content.

POST /tabs/feedback-stream
Content-Type: message/rfc822
X-User-ID: user@domain.com
X-Classification: updates

[raw .eml content]

Header	Required	Description
`X-User-ID`	Yes	User who made the correction
`X-Classification`	Yes	Correct classification (see values above)

Personalization Rule Endpoints

In addition to automatic rules created from feedback, you can manage explicit per-user rules directly.

POST /personalization/rules/create

Coming soon: Creating a rule by file path is not available yet. Use POST /personalization/rules/create-stream to create a rule by streaming the raw message content.

Create an explicit allow or block rule for a user based on an email message.

POST /personalization/rules/create
Content-Type: application/json

{
    "path": "/var/spool/mail/message.eml",
    "userId": "user@domain.com",
    "ruleType": "Sender",
    "label": "ham"
}

Field	Required	Description
`path`	Yes	Path to the email used to derive the rule pattern
`userId`	Yes	User the rule applies to
`ruleType`	Yes	`Sender`, `List`, `Thread`, or `Template`
`label`	Yes	`spam` or `ham`

A stream variant is available at POST /personalization/rules/create-stream using headers X-User-ID, X-Rule-Type, and X-Label.

GET /personalization/rules

GET /personalization/rules?userId=user@domain.com

Returns all personalization rules for the specified user.

DELETE /personalization/rules/remove

DELETE /personalization/rules/remove
Content-Type: application/json

{
    "userId": "user@domain.com",
    "ruleType": "Sender",
    "pattern": "sender@example.com"
}

DELETE /personalization/data

Delete all personalization data for a user (rules, KNN memory, feedback history). Use this for GDPR data deletion requests.

DELETE /personalization/data
Content-Type: application/json

{
    "userId": "user@domain.com"
}

Equivalent endpoints exist for tabs personalization at /personalization/tabs/rules/* and /personalization/tabs/data.