| Method | Path | Summary |
| --- | --- | --- |
| `POST` | `/inbound/raw` | [Inject Raw Message](/content/docs/reference/api/inbound#inject-raw-message/index.html) |

## [Inject Raw Message](/content/docs/reference/api/inbound#inject-raw-message/index.html)

http

```
POST /inbound/raw
```

Stores a raw RFC 5322 message (the request body, any Content-Type, at most 40 MB) as if it had been received, once per recipient inbox in the credential’s scope. The recipient is `X-Recipient`, otherwise every To and Cc address.

Injected messages are marked `received_via: "raw"`. Their trust report never believes the authentication results they carry (headers and provider verdicts are ignored): authentication is `none`, so the trust level is at most `unknown`.

An unrestricted key (`*`) does not imply `inbound_raw`; it must be granted by name.

Injected mail counts toward plan limits like any other inbound mail, even when the trust layer marks it spam or quarantined (its content is yours). On the Free plan, a copy past the monthly or daily allowance (or past storage) is held: it is listed in `held`, not in `messages`, and delivered when the allowance resets or after an upgrade.

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

#### [Headers](/content/docs/reference/api/inbound#headers/index.html)

Field | Description
--- | ---  
`X-Recipient` | `string`

#### [Request body](/content/docs/reference/api/inbound#request-body/index.html)

Content type: `message/rfc822`. Required.

Type: `string (binary)`

#### [Response](/content/docs/reference/api/inbound#response/index.html)

**201** Stored (or held) (`application/json`)

Field | Description
--- | ---  
`count` | `integer` Required
`messages` | [Message[]](/content/docs/reference/api/objects#message/index.html) Required
`errors` | `object[]`
`held` | `object[]`

Each item of `messages` is a [Message](/content/docs/reference/api/objects#message/index.html):

Field | Description
--- | ---  
`inbox_id` | `string` Required
`thread_id` | `string` Required
`message_id` | `string` Required
`labels` | `string[]` Required
`timestamp` | `string (date-time)` Required
`from` | `string` Required
`to` | `string[]` Required
`cc` | `string[]`
`bcc` | `string[]`
`subject` | `string`
`preview` | `string`
`attachments` | [Attachment[]](/content/docs/reference/api/objects#attachment/index.html)
`in_reply_to` | `string`
`references` | `string[]`
`headers` | `Record<string, string>`
`authentication_results` | [MessageAuthenticationResults](/content/docs/reference/api/objects#messageauthenticationresults/index.html)
`size` | `integer` Required
`updated_at` | `string (date-time)` Required
`created_at` | `string (date-time)` Required
`pod_id` | `string` Required
`direction` | `"inbound" | "outbound"` Required
`delivery_status` | `"sent" | "delivered" | "bounced" | "complained"`
`trust_level` | `"verified" | "known" | "unknown" | "suspicious" | "quarantined"`
`reply_to` | `string[]`
`text` | `string`
`html` | `string`
`extracted_text` | `string`
`extracted_html` | `string`
`received_via` | `"raw"`
`held_at` | `string (date-time)`
`trust` | [TrustReport](/content/docs/reference/api/objects#trustreport/index.html)

#### [Errors](/content/docs/reference/api/inbound#errors/index.html)

| Status | Meaning |
| --- | --- |
| `400` | Invalid request |
| `401` | Missing, invalid, expired or revoked credential. |
| `402` | Free plan: organization limit reached. |
| `403` | Lacks permission or scope for this request. |
| `404` | Not found. |
| `500` | Unexpected server error. |

#### [Example](/content/docs/reference/api/inbound#example/index.html)

Request

```
curl -X POST "https://api.machinemail.dev/inbound/raw" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: message/rfc822" \
  --data-binary @body
```

Response 201

```
{
  "count": 1,
  "messages": [
    {
      "inbox_id": "agent@machinemail.dev",
      "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
      "labels": ["UNREAD"],
      "timestamp": "2026-10-01T12:00:00.000Z",
      "from": "Support Agent <agent@machinemail.dev>",
      "to": ["customer@example.com"],
      "cc": ["team@example.com"],
      "bcc": ["audit@example.com"],
      "subject": "Order #1042",
      "preview": "Thanks for the quick reply.",
      "attachments": [
        {
          "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",
          "filename": "invoice.pdf",
          "size": 2048,
          "content_type": "application/pdf",
          "content_disposition": "string",
          "content_id": "string"
        }
      ],
      "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",
      "references": ["string"],
      "headers": {
        "key": "value"
      },
      "authentication_results": {
        "spf": "pass",
        "dkim": "pass",
        "dmarc": "pass",
        "spf_domain": "string",
        "dkim_domain": "string",
        "dmarc_domain": "string",
        "arc_sealer": "string"
      },
      "size": 2048,
      "updated_at": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z",
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "direction": "inbound",
      "delivery_status": "sent",
      "trust_level": "verified",
      "reply_to": ["agent@machinemail.dev"],
      "text": "Thanks for the quick reply.",
      "html": "<p>Thanks for the quick reply.</p>",
      "extracted_text": "Thanks for the quick reply.",
      "extracted_html": "<p>Thanks for the quick reply.</p>",
      "received_via": "raw",
      "held_at": "2026-10-01T12:00:00.000Z",
      "trust": {
        "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": [{}],
          "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": []
          }
        ],
        "attachments": [
          {
            "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",
            "filename": "invoice.pdf",
            "content_type": "application/pdf",
            "risk": "low",
            "reasons": [],
            "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"
      }
    }
  ],
  "errors": [
    {
      "recipient": "string",
      "message": "string"
    }
  ],
  "held": [
    {
      "recipient": "string",
      "reason": "monthly"
    }
  ]
}