Oswerld
MINTSTATSMAILAPI DOCS
Hopmail Agent API

API DOCS

Build agents and external apps that can check inbox access, send notifications, create message receipts, and register payments without handling private message plaintext.

Open HopmailAgent Setup
Production Base

API host

api.luckyoswerld.lol

Wallet-authenticated browser requests use cookies. External agents use API keys with `Authorization: Bearer bm_live_...`.

SIWE
httpOnly cookie
Bearer keys
No plaintext storage
Authentication

Wallet sessions use SIWE and an httpOnly cookie. API agents use bearer keys.

Start a Sign-In With Ethereum flow.

Auth

Public browser request

Parameters

None

Body

None

Returns

nonce
expiresAt

Verify a prepared SIWE message and wallet signature.

Auth

Public browser request; sets httpOnly session cookie

Parameters

None

Body

message: prepared SIWE message
signature: 0x wallet signature

Returns

user
Set-Cookie: basedmail_session

Load the currently signed-in wallet user.

Auth

Wallet session cookie

Parameters

None

Body

None

Returns

user.id
user.address
basename
ensName
avatarUrl
identity refresh fields

Clear the browser session cookie.

Auth

Wallet session cookie

Parameters

None

Body

None

Returns

204 No Content

Ask the backend to refresh ENS and Basename data.

Auth

Wallet session cookie

Parameters

None

Body

None

Returns

user with updated identity fields
identityRefreshError when resolution fails
Inbox Access

Read profiles, rules, and quote whether a wallet can message a recipient.

Read the signed-in creator mailbox profile.

Auth

Wallet session cookie

Parameters

None

Body

None

Returns

displayName
bio
publicInboxEnabled
defaultFeeToken
defaultFeeAmount
protocolFeeBps

Update public inbox settings and default fee settings.

Auth

Wallet session cookie

Parameters

None

Body

displayName?
bio?
publicInboxEnabled?
defaultFeeToken?
defaultFeeAmount?
protocolFeeBps?
allowFreeMessages?

Returns

updated inbox profile

List rules for the signed-in mailbox.

Auth

Wallet session cookie

Parameters

ruleType?
limit?
offset?

Body

None

Returns

array of rules with ruleType, wallet/contract conditions, fee fields, and isEnabled

Create a sender, NFT-holder, token-holder, public, or blocked rule.

Auth

Wallet session cookie

Parameters

None

Body

ruleType
senderAddress? for WALLET/BLOCKED
contractAddress?, chainId?, nftStandard? for NFT_HOLDER
minBalance? for TOKEN_HOLDER
feeToken?
feeAmount?
note?

Returns

created rule

Quote whether a recipient can receive a message and whether payment is required.

Auth

Wallet session cookie or agent bearer key

Parameters

recipientAddress: 0x wallet

Body

None

Returns

allowed
reason
paymentRequired
feeToken?
feeAmount?
protocolFeeBps?
Messages

Store message receipts and delivery status. Private plaintext stays outside Hopmail.

Create metadata for a sent message. Do not send plaintext private content.

Auth

Wallet session cookie or agent bearer key

Parameters

None

Body

recipientAddress
messageHash: 0x-prefixed 32-byte hash
provider: XMTP | INTERNAL | EXTERNAL
externalMessageId?
paymentReceiptId?

Returns

message receipt
status DELIVERED when free
status PENDING when payment is required
403 when rules deny access

List inbox or sent message receipts.

Auth

Wallet session cookie or agent bearer key

Parameters

view: inbox | sent
status?
limit?
offset?

Body

None

Returns

array of message receipts

Read one message receipt by ID.

Auth

Wallet session cookie or agent bearer key

Parameters

id: receipt ID

Body

None

Returns

message receipt

Mark an existing message receipt as read or update status when allowed.

Auth

Wallet session cookie or agent bearer key

Parameters

id: receipt ID

Body

status: PENDING | DELIVERED | READ | REJECTED | EXPIRED

Returns

updated message receipt
Payments

Register payment receipts, verify transactions, and track payment requests.

Register a transaction hash for a message, notification, subscription, or API usage payment.

Auth

Wallet session cookie or agent bearer key

Parameters

None

Body

recipientAddress
tokenAddress? omit for native ETH
amount
chainId
txHash
purpose
messageReceiptId?
paymentRequestId?

Returns

payment receipt with PENDING status

Ask the backend to verify the registered transaction onchain.

Auth

Wallet session cookie or agent bearer key

Parameters

id: payment receipt ID

Body

None

Returns

payment receipt with PENDING, CONFIRMED, or FAILED
linked message becomes DELIVERED after confirmation

List sent or received payment receipts.

Auth

Wallet session cookie or agent bearer key

Parameters

view: received | sent
status?
purpose?
limit?
offset?

Body

None

Returns

array of payment receipts

Create a request for another wallet to pay.

Auth

Wallet session cookie or agent bearer key

Parameters

None

Body

payerAddress
tokenAddress? omit for native ETH
amount
chainId
purpose
note?

Returns

payment request with PENDING status

List payment requests.

Auth

Wallet session cookie or agent bearer key

Parameters

view: received | sent
status?
purpose?
limit?
offset?

Body

None

Returns

array of payment requests
Notifications

Send wallet-native notices and mark them read.

List wallet notifications.

Auth

Wallet session cookie or agent bearer key

Parameters

unread?
limit?
offset?

Body

None

Returns

array of notifications

Send an app or agent update to a wallet.

Auth

Wallet session cookie or agent bearer key

Parameters

None

Body

recipientAddress
title
body
dataJson?
sourceApp?
txHash?

Returns

created notification

Mark a notification as read.

Auth

Wallet session cookie or agent bearer key

Parameters

id: notification ID

Body

None

Returns

updated notification with readAt
Agent Keys

Create API keys in Hopmail, then use them from external apps and agents.

Create a bearer key for an app or agent. The raw key is shown once.

Auth

Wallet session cookie

Parameters

None

Body

name
monthlyLimit?

Returns

api key record
key: raw bm_live_... value shown once

List keys for the signed-in wallet without exposing raw key values.

Auth

Wallet session cookie

Parameters

limit?
offset?

Body

None

Returns

array of key records with usageCount, monthlyLimit, isActive, createdAt

Revoke an API key.

Auth

Wallet session cookie

Parameters

id: API key ID

Body

None

Returns

204 No Content
Contacts

Let creators and agents keep a small wallet address book.

Create a contact for a wallet.

Auth

Wallet session cookie or agent bearer key

Parameters

None

Body

contactAddress
label?
relationship?
notes?

Returns

created contact

List saved contacts.

Auth

Wallet session cookie or agent bearer key

Parameters

relationship?
limit?
offset?

Body

None

Returns

array of contacts

Update a saved contact.

Auth

Wallet session cookie or agent bearer key

Parameters

id: contact ID

Body

contactAddress?
label?
relationship?
notes?

Returns

updated contact

Delete a saved contact.

Auth

Wallet session cookie or agent bearer key

Parameters

id: contact ID

Body

None

Returns

204 No Content

Agent Prompt

Give the creator an API key in Hopmail, then paste this prompt into their agent with the key stored as a secret.

1

API key belongs in private agent config, not the prompt body.

2

Agent should quote inbox access before paid message actions.

3

Agent should use notifications for routine updates.

4

Private plaintext should stay in XMTP or another encrypted channel.

Clipboard Prompt

You are connected to Hopmail by Oswerld for this creator.

Use the creator-provided Hopmail API key as a secret. Never print it, store it in conversation memory, expose it in frontend code, or send it to any service except the Hopmail API.

Configuration:
- API base URL: https://api.luckyoswerld.lol/api
- Auth header: Authorization: Bearer <CREATOR_HOPMAIL_API_KEY>
- Creator wallet: <CREATOR_WALLET_ADDRESS>
- Default recipient wallet: ask the user unless one is supplied

Your job:
1. Help the creator send wallet-native updates through Hopmail.
2. Prefer notifications for agent updates, alerts, summaries, watchlist matches, and public-facing notices.
3. Use message receipts only when the actual private message content is handled through XMTP or another encrypted transport.
4. Never send private plaintext message content to Hopmail. Hopmail stores metadata, receipts, payment status, and notifications.
5. Before sending a message action, call GET /inbox/access?recipientAddress=<wallet> to check whether the recipient allows access and whether payment is required.
6. If payment is required, explain the requirement to the user and wait for explicit approval before creating payment records or asking for a wallet transaction.
7. For notifications, POST /notifications/send with recipientAddress, title, body, optional dataJson, sourceApp, and optional txHash.
8. For message receipts, POST /messages/receipts with recipientAddress, a 0x-prefixed 32-byte messageHash, provider, and optional externalMessageId.
9. Treat 401 as a missing, expired, or revoked API key. Ask the creator for a fresh Hopmail API key.
10. Do not retry 4xx validation errors blindly. Show the user the actionable validation message.

Keep responses concise and tell the creator what Hopmail action you are about to take before sending any request.

Send A Notification

const response = await fetch("https://api.luckyoswerld.lol/api/notifications/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer bm_live_your_agent_key"
  },
  body: JSON.stringify({
    recipientAddress: "0xRecipientWallet",
    title: "Agent update",
    body: "Your watchlist found a new matching Base launch.",
    sourceApp: "my-agent"
  })
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(Array.isArray(error.message) ? error.message.join(", ") : error.message);
}

Message Receipt Body

{
  "recipientAddress": "0xRecipientWallet",
  "messageHash": "0x-prefixed-32-byte-hash",
  "provider": "XMTP",
  "externalMessageId": "xmtp-or-agent-message-id"
}
Rules For Agents

Do not send private plaintext to Hopmail. Store or transmit private content through XMTP or your own encrypted channel.

Use payment and access endpoints before taking paid actions for a user.

Treat 401 as a missing or revoked credential, and do not retry 4xx validation errors blindly.

The raw API key is shown once. Rotate it from Hopmail if it is exposed.