spamcheck

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 8, 2026 License: MIT Imports: 8 Imported by: 0

README

go-spamcheck

Go Reference CI coverage version license imported by

A tiny Go client for Postmark's SpamCheck API. Feed it a raw email, get back a SpamAssassin score — no account, no API key, no bullshit.

What the fuck does it do?

You hand it a full RFC-822 email (headers and all), it POSTs it to Postmark's public SpamCheck endpoint, and hands you back:

  • a score (SpamAssassin points — higher = spammier), and
  • optionally the rule breakdown + human-readable report of every rule that fired.

That's it. One dependency (ctxerrors for error context), stdlib net/http for the request. No account or token required — the endpoint is public.

Installation

go get github.com/psyb0t/go-spamcheck

Usage

One-off check
package main

import (
	"context"
	"fmt"
	"log"

	spamcheck "github.com/psyb0t/go-spamcheck"
)

func main() {
	rawEmail := `From: sender@example.com
To: me@example.com
Subject: FREE MONEY!!!

Congratulations you WON $1000000, click http://spam.example to claim.`

	result, err := spamcheck.Check(context.Background(), rawEmail, spamcheck.ReportShort)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Score:", result.Score) // e.g. "4.8"
}
Reusable client + full report

For repeated calls, build a Client once and reuse it. Ask for ReportLong to get the matched rules and the full report:

client := spamcheck.New()

result, err := client.Check(ctx, rawEmail, spamcheck.ReportLong)
if err != nil {
	log.Fatal(err)
}

score, err := result.ScoreValue() // parse "4.8" -> 4.8
if err != nil {
	log.Fatal(err)
}

if score >= 5.0 {
	fmt.Println("probably spam")
}

for _, rule := range result.Rules {
	fmt.Printf("%s\t%s\n", rule.Score, rule.Description)
}
fmt.Println(result.Report)
Options

New takes functional options:

  • WithBaseURL(url) — point at a different base URL (a proxy, or a test server).
  • WithHTTPDoer(doer) — swap the HTTP client (custom timeout/transport, or a fake in tests). Any type with Do(*http.Request) (*http.Response, error) works.
client := spamcheck.New(
	spamcheck.WithHTTPDoer(&http.Client{Timeout: 5 * time.Second}),
)

Errors

Check returns typed sentinels you can match with errors.Is:

Error Meaning
ErrEmptyEmail the raw email you passed was empty
ErrUnexpectedStatus the API responded with a non-200 status
ErrDecodeResponse the response body couldn't be decoded as JSON
ErrAPIFailure the API responded with success: false (its message is wrapped in)

Every error carries file/line/function context via ctxerrors.

Testing

make test           # unit tests (mocked HTTP, no network)
make test-coverage  # unit tests + coverage gate
make test-real      # hit the LIVE Postmark API — local only, detects upstream API changes

The default suite mocks the HTTP layer, so it's fast and offline. The -real suite (build tag real) hits the actual Postmark endpoint and asserts the response shape still matches — run it locally when you want to catch upstream API drift. It is excluded from CI.

License

MIT. See LICENSE.

Documentation

Overview

Package spamcheck is a tiny client for Postmark's SpamCheck API (https://spamcheck.postmarkapp.com/doc/). It scores a raw RFC-822 email against SpamAssassin rules and returns the score and, optionally, the full matched-rule breakdown plus report.

Index

Constants

View Source
const (
	// DefaultBaseURL is the public Postmark SpamCheck API base URL.
	DefaultBaseURL = "https://spamcheck.postmarkapp.com"
)

Variables

View Source
var (
	// ErrEmptyEmail is returned when the raw email passed to Check is empty.
	ErrEmptyEmail = errors.New("raw email is empty")
	// ErrUnexpectedStatus is returned when the API responds with a non-200 status.
	ErrUnexpectedStatus = errors.New("unexpected response status")
	// ErrDecodeResponse is returned when the API response cannot be decoded.
	ErrDecodeResponse = errors.New("failed to decode response")
	// ErrAPIFailure is returned when the API responds with success=false.
	ErrAPIFailure = errors.New("api reported failure")
)

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client talks to the SpamCheck API.

func New

func New(opts ...Option) *Client

New builds a Client. With no options it uses an http.Client with a 30s timeout against the public Postmark endpoint.

func (*Client) Check

func (c *Client) Check(
	ctx context.Context,
	rawEmail string,
	report Report,
) (*Result, error)

Check submits rawEmail (a full RFC-822 message, headers included) to the SpamCheck API. It returns an error if the email is empty, the request fails, the API responds with a non-200 status, the response cannot be decoded, or the API reports success=false.

type HTTPDoer

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer is the slice of *http.Client this package depends on. Swap in a fake to test without hitting the network.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides the API base URL. Useful for tests or a proxy.

func WithHTTPDoer

func WithHTTPDoer(doer HTTPDoer) Option

WithHTTPDoer sets a custom HTTP client — a fake in tests, or an http.Client with a specific timeout or transport.

type Report

type Report string

Report selects how much detail the API returns.

const (
	// ReportShort asks for the spam score only.
	ReportShort Report = "short"
	// ReportLong asks for the score plus the matched-rule breakdown and report.
	ReportLong Report = "long"
)

type Result

type Result struct {
	Success bool   `json:"success"`
	Score   string `json:"score"`
	Rules   []Rule `json:"rules"`
	Report  string `json:"report"`
	Message string `json:"message"` // set when Success is false
}

Result is the SpamCheck API response. Rules and Report are only populated when the check was requested with ReportLong.

func Check

func Check(
	ctx context.Context,
	rawEmail string,
	report Report,
) (*Result, error)

Check runs a one-off spam check with a default client against the public Postmark endpoint. For repeated calls, build a Client with New and reuse it.

func (*Result) ScoreValue

func (r *Result) ScoreValue() (float64, error)

ScoreValue parses Score into a float64. The API returns the SpamAssassin score as a string; higher means more spammy.

type Rule

type Rule struct {
	Score       string `json:"score"`
	Description string `json:"description"`
}

Rule is a single SpamAssassin rule that fired, with its score contribution.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL