DocumentsSend a document

Documents

Send a document

POST/v1/documents/{id}/send

Emails the document to the client with its pay link. A draft gets its number and first snapshot in the same step.

On first send, the draft takes the next gap-free number of its business and type, a snapshot of the business, client, lines and totals is frozen as version 1, and the status becomes sent. If anything fails, nothing is kept and no number is used. Sending again later re-sends the current version.

Sends are drafts-first: the request must include confirm: true unless the API key or MCP token was created with mode: auto_send. Without it, nothing is sent and you get the preview with confirmation_required. See Drafts and confirmations.

The sender is resolved as in Preview a send. Platform emails count against the monthly allowance (Free 20, Team 100); with your own SMTP there is no limit. A send is idempotent per document, event and channel, so a retried request never emails twice. See Send a document, Platform email and Your own SMTP.

  • Needs confirm: true unless the key or token has mode: auto_send.
  • Idempotency-Key is required for API-key and MCP calls.
  • The platform mailer only works after your email address is verified.
Permission
documents.send
Type
Write. Creates or changes data and writes an audit entry.
Auth
API key, MCP token or signed-in session
Capability
send_document
MCP tool
send_document
CLI
freeinvoiceautomation doc send
Available
At launch, 1 January 2027
send_document
curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/<id>/send \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "confirm": true,
  "channel": "email"
}'
{
  "data": {
    "document": {
      "id": "0193f2b4-2d1e-7a6b-9c80-1f2e3d4c5b6a",
      "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
      "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
      "type": "invoice",
      "status": "sent",
      "number": "INV-2027-0017",
      "issue_date": "2027-02-01",
      "due_date": "2027-02-15",
      "expires_at": null,
      "currency": "USD",
      "fx_rate": "0.7900000000",
      "fx_rate_source": "ecb:2027-02-01",
      "subtotal_minor": "120000",
      "discount_minor": "0",
      "tax_minor": "0",
      "total_minor": "120000",
      "amount_paid_minor": "0",
      "amount_credited_minor": "0",
      "balance_minor": "120000",
      "terms": "Payment due within 14 days.",
      "notes": "Thank you for your business.",
      "accepted_methods": [
        "0193f29f-55aa-7b66-8c77-9d88e99f0a01",
        "0193f29f-55aa-7b66-8c77-9d88e99f0a02"
      ],
      "pdf_template_id": null,
      "late_fees_enabled": false,
      "reminder_sequence_id": null,
      "promise_to_pay_date": null,
      "recurring_schedule_id": null,
      "current_version": 1,
      "first_sent_at": "2027-02-01T10:15:00Z",
      "last_sent_at": "2027-02-01T10:15:00Z",
      "accepted_at": null,
      "paid_at": null,
      "overdue_at": null,
      "voided_at": null,
      "voided_by": null,
      "void_reason": null,
      "source": "api",
      "external_ref": null,
      "client_generated_id": null,
      "lines": [
        {
          "id": "0193f2b4-2d20-7b11-8c01-0a1b2c3d4e01",
          "position": 1,
          "kind": "item",
          "item_id": "0193f2a1-7c4e-7b9a-9f10-3c2d1e0a4b51",
          "description": "Logo design",
          "quantity": "1",
          "unit": "piece",
          "unit_price_minor": "45000",
          "discount_type": null,
          "discount_value": null,
          "tax_rate_id": null,
          "tax_name": null,
          "tax_rate": null,
          "tax_calculation": null,
          "subtotal_minor": "45000",
          "tax_minor": "0",
          "total_minor": "45000",
          "credited_line_id": null
        },
        {
          "id": "0193f2b4-2d20-7b11-8c01-0a1b2c3d4e02",
          "position": 2,
          "kind": "item",
          "item_id": null,
          "description": "Brand guidelines, 12 pages",
          "quantity": "1",
          "unit": null,
          "unit_price_minor": "75000",
          "discount_type": null,
          "discount_value": null,
          "tax_rate_id": null,
          "tax_name": null,
          "tax_rate": null,
          "tax_calculation": null,
          "subtotal_minor": "75000",
          "tax_minor": "0",
          "total_minor": "75000",
          "credited_line_id": null
        }
      ],
      "links": [],
      "pay_url": "https://freeinvoiceautomation.com/pay/q7Xc2mVb9T0kRZ4aNf8sLwE1yHdPu3gJoK6iBt5nM2c",
      "created_at": "2027-02-01T09:12:44Z",
      "updated_at": "2027-02-01T10:15:00Z"
    },
    "message": {
      "id": "0193f2b5-6f7a-7b8c-9d0e-1f2a3b4c5d6e",
      "channel": "email",
      "sender": "platform_mail",
      "to_address": "[email protected], [email protected]",
      "status": "queued",
      "counted_against_quota": true,
      "queued_at": "2027-02-01T10:15:00Z"
    }
  }
}

Authorizations

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

Headers

Idempotency-Keystringrequired
Required for API-key and MCP calls on send calls. Any unique string up to 255 characters; a retry with the same key returns the first response. See Idempotency.

Path Parameters

idstring<uuid>required
Id of the document.

Body

application/json
confirmboolean
Set to true to send. Required unless the API key or MCP token has mode: auto_send; without it you get the preview and confirmation_required.
channelenum<string>default:email
Delivery channel. email at launch; WhatsApp, Telegram and SMS come later.

Available options: email

Response

200 - application/json
documentobject
The document after sending, with its number and pay link.
messageobject
The send record.

Errors

confirmation_required
document_voided
email_not_verified
quota_exceeded
platform_mail_paused
idempotency_key_reused
idempotency_in_progress
upstream_error

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

Suggest editsRaise issue
Preview a sendPreviousRender a PDFNext