---
title: "Trust"
description: "Fetch the trust report for an inbound message: trust level and score, authentication results, sender, content, link and attachment checks and classification."
canonical: "https://machinemail.dev/docs/reference/api/trust"
---

# Trust

> Fetch the trust report for an inbound message: trust level and score, authentication results, sender, content, link and attachment checks and classification.

Source: https://machinemail.dev/docs/reference/api/trust

| Method | Path                                                               | Summary                                                             |
| ------ | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `GET`  | `/v0/inboxes/{inbox_id}/messages/{message_id}/trust`               | [Get Message Trust Report](#get-message-trust-report)               |
| `GET`  | `/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/trust` | [Get Message Trust Report in Pod](#get-message-trust-report-in-pod) |

## Get Message Trust Report

```http
GET /v0/inboxes/{inbox_id}/messages/{message_id}/trust
```

The same object as the message `trust`. `404` for messages without a report (outbound messages).

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### Path parameters

| Field | Type | | Description |
| --- | --- | --- | --- |
| `inbox_id` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). |
| `message_id` | `string` | required | ID of the message. |

#### Response

**200** The trust report (`application/json`)

| Field | Type | | Description |
| --- | --- | --- | --- |
| `level` | `"verified" \| "known" \| "unknown" \| "suspicious" \| "quarantined"` | required | Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for. |
| `score` | `number` | required | 0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1) |
| `basis` | `"trusted_domain"` |  | trusted_domain: the sender is a trusted domain of the organization, pod or inbox (sender.trusted_domain) and the message carries that domain's own DKIM signature. It is verified, or known when it contains instructions to an AI agent, a phishing signal or malware (content.warnings), and never suspicious or quarantined. Agents get its text and attachments, except attachments the virus scan flags. Absent otherwise. |
| `authentication` | `object` | required |  |
| `sender` | `object` | required |  |
| `content` | `object` | required |  |
| `links` | `object[]` | required |  |
| `attachments` | `object[]` | required |  |
| `classification` | `object` | required |  |
| `provider_verdicts` | `object` |  | Spam and virus scans by the receiving mail provider. Only on messages it scanned. |
| `reasons` | `string[]` | required | Human-readable reasons for the verdict. |
| `computed_at` | `string (date-time)` | required | When the report was computed. |

#### Errors

| Status | Meaning                                                                                                                                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, expired or revoked credential.                                                                                                                                                                                       |
| `403`  | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404`  | Not found. Also returned for resources outside the credential scope.                                                                                                                                                                   |
| `500`  | Unexpected server error.                                                                                                                                                                                                               |

Error bodies use the [error envelope](https://machinemail.dev/docs/reference/errors).

#### Example

```bash title="Request"
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/trust" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

```json title="Response 200"
{
  "level": "verified",
  "score": 0.8,
  "basis": "trusted_domain",
  "authentication": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass",
    "aligned": false
  },
  "sender": {
    "address": "agent@machinemail.dev",
    "domain": "example.com",
    "prior_correspondence": false,
    "on_allow_list": false,
    "on_block_list": false,
    "free_mail_provider": false,
    "trusted_domain": {
      "id": "string",
      "domain": "example.com",
      "scope": "org"
    },
    "trusted_domain_shadowed_by": "block"
  },
  "content": {
    "text": "Thanks for the quick reply.",
    "html": "<p>Thanks for the quick reply.</p>",
    "segments": [
      {
        "kind": "body",
        "text": "Thanks for the quick reply."
      }
    ],
    "hidden_text_found": false,
    "zero_width_found": false,
    "tracking_pixels": 1,
    "agent_instructions_detected": false,
    "warnings": ["string"]
  },
  "links": [
    {
      "href": "string",
      "text": "Thanks for the quick reply.",
      "final_url": "https://example.com",
      "domain": "example.com",
      "display_mismatch": false,
      "shortener": false,
      "suspicious": false,
      "reasons": ["string"]
    }
  ],
  "attachments": [
    {
      "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "risk": "low",
      "reasons": ["string"],
      "extracted_text": "Thanks for the quick reply."
    }
  ],
  "classification": {
    "is_spam": 0.8,
    "is_phishing": 0.8,
    "contains_instructions_to_agent": 0.8,
    "requests_credentials_or_payment": 0.8,
    "urgency": 0.8,
    "category": "transactional",
    "language": "string",
    "backend": "string",
    "input_hash": "string",
    "cached": false
  },
  "provider_verdicts": {
    "spam": "pass",
    "virus": "pass",
    "source": "string"
  },
  "reasons": ["string"],
  "computed_at": "2026-10-01T12:00:00.000Z"
}
```

## Get Message Trust Report in Pod

```http
GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/trust
```

Same as Get Message Trust Report (`GET /v0/inboxes/{inbox_id}/messages/{message_id}/trust`), limited to the pod.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `message_read`.

#### Path parameters

| Field | Type | | Description |
| --- | --- | --- | --- |
| `pod_id` | `string` | required | ID of the pod. |
| `inbox_id` | `string` | required | ID of the inbox: its email address, as in AgentMail (inbox_id == email). |
| `message_id` | `string` | required | ID of the message. |

#### Response

**200** The trust report (`application/json`)

| Field | Type | | Description |
| --- | --- | --- | --- |
| `level` | `"verified" \| "known" \| "unknown" \| "suspicious" \| "quarantined"` | required | Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for. |
| `score` | `number` | required | 0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1) |
| `basis` | `"trusted_domain"` |  | trusted_domain: the sender is a trusted domain of the organization, pod or inbox (sender.trusted_domain) and the message carries that domain's own DKIM signature. It is verified, or known when it contains instructions to an AI agent, a phishing signal or malware (content.warnings), and never suspicious or quarantined. Agents get its text and attachments, except attachments the virus scan flags. Absent otherwise. |
| `authentication` | `object` | required |  |
| `sender` | `object` | required |  |
| `content` | `object` | required |  |
| `links` | `object[]` | required |  |
| `attachments` | `object[]` | required |  |
| `classification` | `object` | required |  |
| `provider_verdicts` | `object` |  | Spam and virus scans by the receiving mail provider. Only on messages it scanned. |
| `reasons` | `string[]` | required | Human-readable reasons for the verdict. |
| `computed_at` | `string (date-time)` | required | When the report was computed. |

#### Errors

| Status | Meaning                                                                                                                                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, expired or revoked credential.                                                                                                                                                                                       |
| `403`  | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). |
| `404`  | Not found. Also returned for resources outside the credential scope.                                                                                                                                                                   |
| `500`  | Unexpected server error.                                                                                                                                                                                                               |

Error bodies use the [error envelope](https://machinemail.dev/docs/reference/errors).

#### Example

```bash title="Request"
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/trust" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

```json title="Response 200"
{
  "level": "verified",
  "score": 0.8,
  "basis": "trusted_domain",
  "authentication": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass",
    "aligned": false
  },
  "sender": {
    "address": "agent@machinemail.dev",
    "domain": "example.com",
    "prior_correspondence": false,
    "on_allow_list": false,
    "on_block_list": false,
    "free_mail_provider": false,
    "trusted_domain": {
      "id": "string",
      "domain": "example.com",
      "scope": "org"
    },
    "trusted_domain_shadowed_by": "block"
  },
  "content": {
    "text": "Thanks for the quick reply.",
    "html": "<p>Thanks for the quick reply.</p>",
    "segments": [
      {
        "kind": "body",
        "text": "Thanks for the quick reply."
      }
    ],
    "hidden_text_found": false,
    "zero_width_found": false,
    "tracking_pixels": 1,
    "agent_instructions_detected": false,
    "warnings": ["string"]
  },
  "links": [
    {
      "href": "string",
      "text": "Thanks for the quick reply.",
      "final_url": "https://example.com",
      "domain": "example.com",
      "display_mismatch": false,
      "shortener": false,
      "suspicious": false,
      "reasons": ["string"]
    }
  ],
  "attachments": [
    {
      "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "risk": "low",
      "reasons": ["string"],
      "extracted_text": "Thanks for the quick reply."
    }
  ],
  "classification": {
    "is_spam": 0.8,
    "is_phishing": 0.8,
    "contains_instructions_to_agent": 0.8,
    "requests_credentials_or_payment": 0.8,
    "urgency": 0.8,
    "category": "transactional",
    "language": "string",
    "backend": "string",
    "input_hash": "string",
    "cached": false
  },
  "provider_verdicts": {
    "spam": "pass",
    "virus": "pass",
    "source": "string"
  },
  "reasons": ["string"],
  "computed_at": "2026-10-01T12:00:00.000Z"
}
```