Crate spamhaus_submission

Expand description

An async client for the Spamhaus Submission Portal API.

The Submission Portal lets you report malicious IP addresses, domains, URLs and emails to Spamhaus, and read back what their review found.

§Get a token

Go to https://auth.spamhaus.org/account, find “API Key Creation” and click “Create Key”. Spamhaus shows the key one time only, so copy it then.

§Send a report

use spamhaus_submission::{ApiToken, Client, Outcome, Reason, ThreatTypeCode};

let client = Client::new(ApiToken::new(std::env::var("SPAMHAUS_TOKEN").unwrap())?)?;

let outcome = client
    .submit_ip(
        ThreatTypeCode::new("spam")?,
        Reason::new("found on a forum")?,
        "221.22.34.2".parse().unwrap(),
    )
    .await?;

match outcome {
    Outcome::Accepted(accepted) => println!("stored as {}", accepted.id.as_str()),
    Outcome::AlreadyReported => println!("Spamhaus already holds this one"),
}

§Read your history

use spamhaus_submission::{ApiToken, Client, ListParams, Status};

let client = Client::new(ApiToken::new("token")?)?;

for record in client.list_all(ListParams::default()).await? {
    match record.status {
        Status::Pending => println!("{}: not reviewed yet", record.object),
        Status::Clear { .. } => println!("{}: in no dataset", record.object),
        Status::Listed { datasets, .. } => {
            let names: Vec<_> = datasets.iter().map(|d| d.as_str()).collect();
            println!("{}: listed in {}", record.object, names.join(", "));
        }
    }
}

§Design

Values you send are checked when you build them, so a request that Spamhaus is certain to reject never leaves the process. Values Spamhaus sends back are not checked the same way: a change on their side must not turn a working call into a parse failure.

Structs§

Accepted: What Spamhaus stored for a report it accepted.
ApiToken: A Submission Portal API token.
Client: A client for the Submission Portal API.
ClientBuilder: Collects the settings for a Client.
Counts: How many reports you sent in the last 30 days, and how many matched.
Dataset: The name of a Spamhaus dataset, such as SBL or XBL.
Domain: A domain name to report, for example www.baddomain.com.
ListParams: Which page of your report history to read.
RawEmail: The full source of an email to report, headers included.
Reason: The reason for a report, as free text.
Record: One report in your history, with its review status.
Report: One report, ready to send.
SubmissionId: The identifier Spamhaus gives a report.
ThreatType: One entry from the threat type list.
ThreatTypeCode: A code that names the kind of threat you report, such as spam.
UrlTarget: A URL to report.

Enums§

Attributes: What Spamhaus read out of a reported value.
Error: Anything that can go wrong in a call to the Submission Portal API.
Outcome: The result of sending a report.
Status: Where a report stands in the Spamhaus review.
SubmissionKind: The kind of thing a report is about.
Target: The thing you report.
ThreatScope: Which kinds of report a threat type can be used with.
ValidationError: A value that does not satisfy a documented limit of the Submission Portal API.

Constants§

DEFAULT_BASE_URL: The address of the live Submission Portal API.