BSV blockchainBSV blockchain

Send a message to one or more recipients' message boxes

POST/sendMessage

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.

Show outputs properties
outputIndexintegerrequired

Index of this output in the BEEF transaction.

protocol"wallet payment" | "basket insertion"required
paymentRemittanceobject
Show paymentRemittance properties
derivationPrefixstring

Base64-encoded derivation prefix.

derivationSuffixstring

Base64-encoded derivation suffix.

senderIdentityKeystring

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).

descriptionstring

Human-readable explanation.

Request
curl -X POST "https://{host}/sendMessage" \
  -H "Content-Type: application/json" \
  -H "x-bsv-auth-identity-key: <x-bsv-auth-identity-key>" \
  -d '{
  "message": {
    "recipient": "string",
    "recipients": [
      "string"
    ],
    "messageBox": "string",
    "messageId": "string",
    "body": "string"
  },
  "payment": {
    "tx": [
      0
    ],
    "outputs": [
      {
        "outputIndex": 0,
        "protocol": "wallet payment",
        "paymentRemittance": {
          "derivationPrefix": "string",
          "derivationSuffix": "string",
          "senderIdentityKey": "string",
          "customInstructions": null
        },
        "insertionRemittance": {
          "basket": "string",
          "customInstructions": "string",
          "tags": [
            "string"
          ]
        }
      }
    ],
    "description": "string",
    "labels": [
      "string"
    ],
    "seekPermission": true
  }
}'
Response
{
  "status": "success",
  "message": "string",
  "results": [
    {
      "recipient": "string",
      "messageId": "string"
    }
  ]
}