Trust report · MachineMail Docs

Every inbound message carries a trust object. It is computed once, when the message arrives, and returned unchanged on every read. Field names are snake_case, like the rest of the API. Optional fields that have no value are left out rather than sent as null.

Shape

TrustReport

interface TrustReport {
  level: 'verified' | 'known' | 'unknown' | 'suspicious' | 'quarantined';
  score: number; // 0..1, higher is safer
  authentication: {
    spf: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none';
    dkim: 'pass' | 'fail' | 'none';
    dmarc: 'pass' | 'fail' | 'none';
    aligned: boolean;
  };
  sender: {
    address: string;
    domain: string;
    prior_correspondence: boolean;
    on_allow_list: boolean;
    on_block_list: boolean;
    free_mail_provider: boolean;
  };
  content: {
    text: string; // agent-safe body
    html?: string; // sanitised HTML, only when the message had HTML
    segments: Array<{ kind: 'body' | 'quote' | 'signature' | 'hidden' | 'disclaimer'; text: string }>;
    hidden_text_found: boolean;
    zero_width_found: boolean;
    tracking_pixels: number;
  };
  links: Array<{
    href: string;
    text?: string;
    final_url?: string;
    domain: string;
    display_mismatch: boolean;
    shortener: boolean;
    suspicious: boolean;
    reasons: string[];
  }>;
  attachments: Array<{
    attachment_id: string;
    filename?: string;
    content_type?: string;
    risk: 'low' | 'medium' | 'high';
    reasons: string[];
    extracted_text?: string;
  }>
  classification: {
    is_spam: number;
    is_phishing: number;
    contains_instructions_to_agent: number;
    requests_credentials_or_payment: number;
    urgency: number;
    category: 'transactional' | 'conversation' | 'notification' | 'newsletter' | 'otp' | 'bounce' | 'other';
    language?: string;
    backend: string;
  };
  reasons: string[];
  computed_at: string; // ISO 8601
}

level

The verdict. It is decided by the first rule that matches:

Order Level When
1 quarantined The sender is on the inbox’s receive block list.
2 quarantined is_phishing or contains_instructions_to_agent is 0.8 or higher, or text hidden from human readers contains instructions to an AI agent.
3 suspicious SPF, DKIM or DMARC failed; a link’s visible text names a different domain than its destination; an attachment is high risk; or is_spam, is_phishing, contains_instructions_to_agent or requests_credentials_or_payment is 0.5 or higher.
4 verified DMARC passed and is aligned with the From domain, and your organization has written to the sender before or the sender is on the allow list.
5 known At least one of SPF, DKIM or DMARC passed. Mail from an address on a domain every MachineMail organization shares needs prior correspondence with that exact address or an allow-list entry as well.
6 unknown Nothing passed, and nothing looked bad.

Urgency never changes the level on its own: one-time codes are urgent by design.

score

A number from 0 to 1, higher is safer, rounded to three decimals. Use it to rank messages within a level, not as a replacement for the level. It is a weighted sum of five components:

Component Weight Value
authentication 0.25 1.0 when DMARC passes aligned; 0.8 for an aligned SPF or DKIM pass; 0.5 for an unaligned pass; 0.3 when nothing passed; 0 when anything failed
sender 0.20 1.0 on the allow list; 0.9 with prior correspondence with the address; 0.7 when you have written only to someone else at its domain; 0.4 first contact; 0 on the block list
content 0.35 1 minus the largest of contains_instructions_to_agent, is_phishing, 0.8 × is_spam and 0.6 × requests_credentials_or_payment
links 0.10 1 minus 0.6 per mismatched link and 0.3 per other suspicious link, floored at 0
attachments 0.10 1 with no risky attachments; 0.6 with a medium-risk one; 0 with a high-risk one

The result is then capped by level: at most 0.15 for quarantined, 0.45 for suspicious and 0.7 for unknown. A first-contact, fully authenticated, clean message scores about 0.87.

authentication

Field Values Meaning
spf pass, fail, softfail, neutral, none SPF result for the envelope sender.
dkim pass, fail, none pass if any DKIM signature verified.
dmarc pass, fail, none DMARC result.
aligned boolean A passing DKIM d= domain or SPF domain shares the From address’s organisational domain.

sender

Field Meaning
address The From address, lowercased.
domain Its domain.
prior_correspondence Your organization has sent mail to this address before.
on_allow_list The sender matches the inbox’s receive allow list.
on_block_list The sender matches the inbox’s receive block list.
free_mail_provider The domain is a consumer mail provider.

Prior correspondence

prior_correspondence looks at the mail every inbox in your organization has sent, not only the inbox that received the message.

The lookup reads the 500 most recent messages sent from the receiving inbox and the 500 most recent sent from your whole organization.

content

Field Meaning
text The agent-safe body: only the body segments, joined.
html Sanitised HTML.
segments The whole message cut into labelled pieces.
hidden_text_found Prose was deliberately hidden from a human reader.
zero_width_found Zero-width or Unicode tag characters were removed.
tracking_pixels How many tracking pixels were removed.

links

Field Meaning
href The link target as written.
text The visible link text.
final_url Where the link ends up after redirects.
domain The host of href.
display_mismatch The text shows one domain and the link goes to another.
shortener The host is a URL shortener.
suspicious At least one structural red flag fired.
reasons Why each flag fired.

attachments

Field Meaning
attachment_id Matches the message’s attachments[].attachment_id.
filename As sent.
content_type As declared by the sender.
risk low, medium or high.
reasons Why the risk was raised.
extracted_text Text from attachments.

classification

Field Meaning
is_spam Probability, 0 to 1, that this is unsolicited bulk or commercial mail.
is_phishing Probability that it impersonates someone to steal credentials, money or access.
contains_instructions_to_agent Probability that it contains prompt injection.
requests_credentials_or_payment Probability that it asks for sensitive information.
urgency How much time pressure it puts on the reader, 0 to 1.
category transactional, conversation, etc.
language ISO 639-1 code of the body’s main language, when one was detected.
backend What produced the numbers.

reasons

Plain-English sentences explaining the level’s own explanation and other signals.

computed_at

When the report was computed, as an ISO 8601 timestamp.