/api/qmail/local/inbox-fee

GET

Look up the inbox fee stored for a contact by serial number. Local database only — does not contact RAIDA. Handler: api_handle_qmail_inbox_fee.

http://localhost:8081/api/qmail/local/inbox-fee?sn=16777216

Description

Returns the contact record’s configured inbox_fee for the given serial number. The amount is emitted as an exact decimal CloudCoin number (microunit-backed; representation supports 0.0001 CC granularity). Beacons and local compose UIs use this value when deciding how large an inbox-fee locker to fund for Tell.

This endpoint is not a full send-cost calculator. It does not estimate storage fees, accept file lists, or accept recipient address lists. Storage-fee preflight (size-based formula, files= / stripe_bytes, estimated_server_count) lives on /api/qmail/local/can-send (api_handle_qmail_can_send), not here.

Inbox fee vs storage fee

Inbox fee (this endpoint): per-recipient Tell payment from the contact/DRD record (or client default when composing). Decimal CC — often a whole amount such as 10, but fractions are valid.

Storage fee (upload path / can-send estimate): interim pricing is 0.01 CC per MiB of per-server stripe data, always ceil to the next 0.01 CC, free under the welfare allowance (default 1 MiB). Example: 2.5 MiB per server → 0.03 CC per server. See Upload payment & pricing.

The old flat rule “1 CC per server per file + 10 CC per recipient” is obsolete and must not be used for estimates.

Parameters

ParamTypeRequiredDescription
sn integer Yes Contact serial number (must be > 0). Looked up in the local QMail contacts database.

Legacy alias: /api/qmail/inbox-fee hits the same handler (used by some raidax beacon paths).

Response

{
  "command": "inbox-fee",
  "success": true,
  "request_id": "…",
  "sn": 16777216,
  "denomination": 0,
  "inbox_fee": 10
}
FieldTypeDescription
commandstringAlways "inbox-fee".
successbooltrue when the contact was found.
request_idstringCorrelation id for logs.
snintegerSerial number from the contact record.
denominationintegerContact address denomination.
inbox_feenumberExact decimal CC amount (e.g. 10, 0.5, 0.0001). From the contact row; not recomputed by this handler.

Fractional example (contact override):

{
  "command": "inbox-fee",
  "success": true,
  "request_id": "…",
  "sn": 2841,
  "denomination": 1,
  "inbox_fee": 0.25
}

Errors

HTTPMessage
400Missing required parameter: sn
400Invalid sn parameter
404Contact not found
500QMail database not available / Database error

Example

curl "http://localhost:8081/api/qmail/local/inbox-fee?sn=16777216"

Related