Inserts a message into each recipient’s named message box. If the box
does not exist it is created automatically.
Payment logic
If deliveryFee > 0 (set by server policy) a payment is required
with output[0] assigned to the server.
If any recipient’s recipientFee > 0 (set by the recipient) additional
per-recipient outputs must be included.
If a recipient has recipientFee === -1 (blocked) the entire request
fails with 403 before any DB writes.
Recipients must be unique after public-key canonicalization. Duplicate
compressed/uncompressed representations are rejected before fee or
message-ID allocation.
Deduplication Messages with a duplicate messageId are silently
ignored (ON CONFLICT IGNORE). If the database raises a hard duplicate-key
error, a 400 is returned.
Multi-recipient output routing When sending to multiple recipients
each output in payment.outputs (after the optional server output at
index 0) can include customInstructions containing a JSON object with
a recipientIdentityKey field. If present, the server routes that output
to the identified recipient. Otherwise, outputs are mapped positionally
to recipients who require a fee.
Body application/json
messageobjectrequired
A message to be stored in a recipient’s message box. The recipient /
recipients field carries either a single key or an array. When multiple
recipients are provided, messageId must be an array of the same length
with one ID per recipient (same order).
Show message properties
recipientstring
Identity key of the recipient, or an array of recipient identity keys.
Alias: recipients (array form only). Both fields are accepted for
back-compat but must not be used simultaneously.
recipientsstring[]
Preferred plural form. Takes precedence over recipient when both are present. Compressed and uncompressed encodings of the same key count as one recipient and must not be repeated.
messageBoxstringrequired
Named message box (e.g. payment_inbox, notifications).
messageIdstringrequired
Unique identifier(s) for the message(s) — typically an HMAC. When
recipients has more than one entry, messageId must be an array
of the same length with one ID per recipient.
bodystringrequired
Serialized message payload. The official client serializes object
bodies before sending them.
paymentobject
Optional payment attached to a message send. Required when the recipient
has set a recipientFee > 0 or the server has a deliveryFee > 0.
Show payment properties
txinteger[]required
Atomic BEEF (Background Evaluation Extended Format) encoded as a byte array.
outputsobject[]required
Output list. When a server delivery fee applies, output[0] must pay
the per-recipient delivery fee multiplied by the number of recipients.
Subsequent outputs are recipient-side.
Compressed secp256k1 public key encoded as a 66-character hex string.
customInstructionsany
Arbitrary per-output routing instructions. The server attempts to
parse this as JSON. If the parsed object contains a
recipientIdentityKey string field, the output is routed to that
recipient (batch sends only).
insertionRemittanceobject
Show insertionRemittance properties
basketstring
customInstructionsstring
Same recipientIdentityKey convention as paymentRemittance.customInstructions.
tagsstring[]
descriptionstringrequired
Human-readable description for wallet internalization.
labelsstring[]
seekPermissionboolean
Response
Message(s) sent successfully.
status"success"
messagestring
Human-readable summary (e.g. “Your message has been sent to 1 recipient(s).”).
resultsobject[]
Show results properties
recipientstring
Compressed secp256k1 public key encoded as a 66-character hex string.
messageIdstring
Bad request. Possible codes:
ERR_MESSAGE_REQUIRED
ERR_INVALID_MESSAGEBOX
ERR_INVALID_MESSAGE_BODY
ERR_RECIPIENT_REQUIRED
ERR_MESSAGEID_REQUIRED
ERR_MESSAGEID_COUNT_MISMATCH
ERR_INVALID_MESSAGEID
ERR_INVALID_RECIPIENT_KEY
ERR_MISSING_PAYMENT_TX
ERR_MISSING_DELIVERY_OUTPUT
ERR_INSUFFICIENT_PAYMENT
ERR_INSUFFICIENT_OUTPUTS
ERR_MISSING_RECIPIENT_OUTPUTS
ERR_DUPLICATE_MESSAGE
status"error"
codestring
Machine-readable error code (see specs/errors.md).
descriptionstring
Human-readable explanation.
Authentication required (ERR_AUTH_REQUIRED).
status"error"
codestring
Machine-readable error code (see specs/errors.md).
descriptionstring
Human-readable explanation.
One or more recipients have blocked the sender (ERR_DELIVERY_BLOCKED).
The blockedRecipients field lists the affected identity keys.
status"error"
codestring
Machine-readable error code (see specs/errors.md).
descriptionstring
Human-readable explanation.
blockedRecipientsstring[]
Internal server error (ERR_INTERNAL, ERR_INTERNALIZE_FAILED).
status"error"
codestring
Machine-readable error code (see specs/errors.md).