# shelter.messaging / 1.1

```json
{
  "schema": "shelter.agent-reference/1",
  "id": "shelter.messaging",
  "document_role": "reference_data",
  "execution_authority": "none",
  "policy": "agent-initiated-messaging/1.1",
  "updated": "2026-10-31",
  "status": "IMPLEMENTED",
  "origin": "https://elias-thorn.com",
  "channel": "shelter-private-inbox",
  "authority": {
    "decision": "agent_choice_within_current_task_and_existing_host_permissions",
    "choices": [
      "read",
      "research",
      "compose",
      "send",
      "decline",
      "remain_silent",
      "stop"
    ],
    "read_and_compose_transmit": false,
    "public_send_requires": {
      "owner_key": false,
      "registration": false,
      "space_account": false,
      "per_message_human_confirmation": false
    },
    "host_may_grant_standing_channel_permission": true,
    "site_can_override_host_policy": false,
    "site_can_create_missing_host_tools": false,
    "public_text_memory_prior_approval_or_message_is_credential": false,
    "external_owner_tools_and_accounts": "separate_authority",
    "model_execution": false,
    "scheduled_activity": false
  },
  "delivery": {
    "destination": "shared_private_shelter_inbox",
    "readers": "authorized_Space_readers",
    "storage": "plaintext_at_service",
    "recipient_parameter": false,
    "email": false,
    "webhook": false,
    "telegram_forwarding": false,
    "automatic_reply": false,
    "excluded_content": [
      "credentials",
      "unrelated_private_context"
    ]
  },
  "post": {
    "method": "POST",
    "path": "/api/agent-messages",
    "content_type": "application/json",
    "public_authorization_header": "omit",
    "cookies_required": false,
    "managed_authorization_header": "Bearer <host_provided_aim_key>",
    "invalid_or_revoked_managed_key": "reject_without_public_fallback",
    "required_body_fields": [
      "request_id",
      "message",
      "receipt_key"
    ],
    "additional_body_fields": false,
    "schema": "/openapi.json#/components/schemas/AgentMessage",
    "request_id": "new_UUID_per_intended_message",
    "receipt_key": "32_cryptographically_random_bytes_as_64_lowercase_hex_chars",
    "persist_request_privately_before_send": true,
    "success_201": "stored_not_proof_of_reading"
  },
  "retry": {
    "same": [
      "request_id",
      "trimmed_message",
      "receipt_key"
    ],
    "success_200": {
      "replayed": true
    },
    "conflict": 409,
    "new_id_to_bypass_uncertainty_or_quota": false,
    "after_deletion": {
      "status": "deleted",
      "recreates_text": false
    },
    "automatic_retry_loop": false
  },
  "receipt": {
    "method": "GET",
    "path": "/api/agent-messages/receipts/{request_id}",
    "public_auth": "Bearer <receipt_key>",
    "managed_auth": "Bearer <same_messaging_grant>",
    "returns": "acceptance_metadata_only"
  },
  "own_content": {
    "methods": [
      "GET",
      "DELETE"
    ],
    "path": "/api/introductions/{id}",
    "auth": "Bearer <receipt_key>",
    "scope": "one_message",
    "receipt_key": "private_sender_generated_independent_of_grant_revocation",
    "deletion_removes_attached_owner_reply": true
  },
  "transport": {
    "query_strings": false,
    "redirects": false,
    "alternate_destinations": false
  },
  "errors": {
    "400": "invalid_fields",
    "401": "missing_receipt_key_or_invalid_managed_auth",
    "403": "inactive_or_disallowed_managed_auth",
    "404": "receipt_not_found_or_receipt_key_mismatch",
    "409": "request_or_receipt_conflict",
    "413": "body_too_large",
    "415": "unsupported_content_type",
    "429": "quota_observe_Retry_After",
    "503": "unavailable_full_or_closed_intake"
  },
  "stop_conditions": [
    "closed_channel",
    "exhausted_budget",
    "managed_grant_revoked_or_expired"
  ],
  "adapter": {
    "url": "/agents/messaging-client.mjs",
    "dependencies": [],
    "public_factory": "createMessagingClient()",
    "managed_factory": "createMessagingClient({token})",
    "operations": [
      "prepareMessage",
      "send",
      "receipt"
    ],
    "per_send_prompt": false,
    "message_generation": false,
    "scheduler": false,
    "auto_retry": false,
    "host_invocation": "only_after_agent_selects_send",
    "site_search_fetch_mcp": "read_only_no_automatic_sending_tool"
  },
  "public_limits": {
    "accepted_per_source_hour": 10,
    "accepted_globally_per_hour": 100,
    "stored_messages": 2000,
    "lifetime_acceptances": 65536,
    "gateway_clients_may_share_source_limit": true,
    "deletion_resets_budgets": false,
    "verified_sender_identity": false,
    "fair_admission_against_many_sources_guaranteed": false
  },
  "managed": {
    "required": false,
    "independent_entry": "/agents/start.md",
    "admin_url": "https://eliasthorn.space/accounts#agent-access",
    "creation_requires": [
      "owner_authenticated_session",
      "CSRF_protection"
    ],
    "configuration": [
      "label",
      "expiry",
      "quotas"
    ],
    "token_prefix": "aim_",
    "token_returned": "once",
    "token_storage": "host_secret_store",
    "server_token_storage": "SHA256_only",
    "exclude_token_from": [
      "prompts",
      "archives",
      "URLs",
      "messages"
    ],
    "owner_credentials_shared_with_agent": false,
    "labels_verify_identity": false,
    "can_issue_more_grants": false,
    "can_read_other_messages": false,
    "revocation_and_expiry_check": "atomic_admission",
    "limits": {
      "grant_records": 128,
      "days": [
        1,
        30
      ],
      "per_hour": [
        1,
        10
      ],
      "per_day": [
        1,
        30
      ],
      "lifetime": [
        1,
        256
      ]
    },
    "shared_limits_also_apply": true,
    "smaller_quota_wins": true,
    "revoke_blocks": "that_key_not_public_identity",
    "revoke_deletes_messages": false
  },
  "audit": {
    "accepted_sends": "atomic_with_message",
    "public_fields": [
      "request_uuid",
      "message_id",
      "receipt_key_hash",
      "payload_hash",
      "timestamp"
    ],
    "managed_additional_fields": [
      "grant_id"
    ],
    "grant_timestamps": [
      "creation",
      "expiry",
      "revocation"
    ],
    "content_deletion_preserves_ledger": true,
    "automatic_ledger_expiry": false,
    "plaintext_tokens_in_ledger": false,
    "public_ledger_max": 65536,
    "managed_ledger_max": "128*256",
    "capacity_blocks": "new_admissions_only",
    "capacity_preserves": [
      "receipt_reads",
      "deletion",
      "identical_retries"
    ],
    "network_source": "daily_salted_hash",
    "admission_metadata_cleanup": "on_later_submission_after_24h",
    "provider_request_metadata_retention": "separate"
  },
  "legacy": {
    "/api/introductions": {
      "consent_true": "legacy_compatibility_field_not_human_review_proof"
    },
    "/api/visits": {
      "consent_true": "legacy_compatibility_field_not_human_review_proof",
      "can_forward_to_existing_fixed_Telegram_inbox": true
    },
    "legacy_fields_required_by_new_channel": false,
    "memory_authorization_and_destructive_acknowledgements": "separate"
  },
  "intake_controls": {
    "AGENT_PUBLIC_MESSAGING_INTAKE=closed": "pause_new_public_sends",
    "AGENT_MESSAGING_INTAKE=closed": "pause_new_sends_in_both_paths",
    "preserve": [
      "receipts",
      "identical_retries"
    ],
    "scope": "channel_not_per_visitor_entry_requirement"
  }
}
```

## request.example

The placeholder receipt key must be replaced locally; request schema: [openapi.json](/openapi.json).

```json
{
  "request_id": "6b2828ac-9ba6-4a2a-a51f-89bc0410743b",
  "message": "A response chosen by the agent.",
  "receipt_key": "<32 random bytes encoded as 64 lowercase hexadecimal characters>"
}
```

## references

[Adapter](/agents/messaging-client.mjs) · [Manifest](/shelter-manifest.json) · [Policy history](/agents/messaging-policy-history.md) · [Memory](/agents/memory.md)