DocumentsPreview a send

Documents

Preview a send

POST/v1/documents/{id}/send-preview

Shows exactly what sending would do: sender, recipients, subject, message and quota use. Nothing is sent.

Call this before Send a document, and show the result to a person when an AI or integration prepared the send. The sender is chosen in this order: document override, client preference, business default, then the platform mailer, which is used only when the account still has platform emails left this month.

The preview reports problems the send would hit, such as an unverified email address or a used-up allowance, so you can fix them first. It changes nothing and uses no quota. See Send a document.

Permission: documents.view
Type: Read-only. Changes nothing.
Auth: API key, MCP token or signed-in session
Capability: preview_send
MCP tool: preview_send
CLI: freeinvoiceautomation doc send --preview
Available: At launch, 1 January 2027

preview_send

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/<id>/send-preview \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "channel": "email"
}'

{
  "data": {
    "document_id": "0193f2b4-2d1e-7a6b-9c80-1f2e3d4c5b6a",
    "number": null,
    "channel": "email",
    "sender": "platform_mail",
    "connection_id": null,
    "to": [
      "[email protected]",
      "[email protected]"
    ],
    "reply_to": "[email protected]",
    "subject": "Invoice from Northwind Studio",
    "body": "Hello Amira, please find your invoice for 1,200.00 USD, due on 15 February 2027. You can view and pay it here: {pay link}",
    "attach_pdf": true,
    "counts_against_quota": true,
    "warnings": []
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Path Parameters

idstring<uuid>required

Id of the document.

Body

application/json

channelenum<string>default:email

Channel to preview. email at launch.

Available options: email

Response

200 - application/json

document_idstring<uuid>

The document that would be sent.

numberstring | null

The document number, or null for a draft: a draft takes the next number of its sequence when it is actually sent.

channelenum<string>

Channel that would be used. email at launch.

Available options: email

senderenum<string>

Sender that would be used: your own SMTP, or the platform mailer when there is no SMTP and quota is left.

Available options: smtp, platform_mail

connection_idstring<uuid> | null

The SMTP connection, or null for the platform mailer.

tostring[]

Recipients: the client's email and every contact that receives documents.

reply_tostring | null

Reply-To address (the business email on platform sends).

subjectstring

Email subject from the message template.

bodystring

Email text from the message template, with variables filled in.

attach_pdfboolean

Whether the PDF is attached.

counts_against_quotaboolean

true when the platform mailer would be used, so the send uses one platform email of your monthly allowance.

warningsstring[]

Plain-English warnings, e.g. that 80% of the platform email allowance is used.

Errors

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

List overdue invoicesPrevious Send a documentNext

preview_send

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/<id>/send-preview \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "channel": "email"
}'

{
  "data": {
    "document_id": "0193f2b4-2d1e-7a6b-9c80-1f2e3d4c5b6a",
    "number": null,
    "channel": "email",
    "sender": "platform_mail",
    "connection_id": null,
    "to": [
      "[email protected]",
      "[email protected]"
    ],
    "reply_to": "[email protected]",
    "subject": "Invoice from Northwind Studio",
    "body": "Hello Amira, please find your invoice for 1,200.00 USD, due on 15 February 2027. You can view and pay it here: {pay link}",
    "attach_pdf": true,
    "counts_against_quota": true,
    "warnings": []
  }
}