Email an invoice to its client
Email an invoice to its client. Emails the invoice PDF (and timesheet PDF when enabled) through the workspace's configured sender. A DRAFT becomes SENT atomically when the provider accepts the message; SENT/PAID invoices are re-sent unchanged; CANCELLED invoices are rejected (409). Every recipient must already be on file for the invoice's client (billing email, client email or a client contact); any other address is rejected with 422 — add it as a client contact in Hoursmith first. Omitted `to` uses the client's default billing recipient, exactly as the app pre-fills it. A provider failure returns 200 with status `failed` and `sendError`, and the invoice is unchanged. A NOT SENT warning means nothing was delivered. A NOT CONFIRMED warning means the provider call had started (a timeout, or an answer that came too late to record): the email may have reached the recipient, so check with them before sending again. Send and remind share the app's send budget: a one-minute cooldown per invoice (send and remind share it), 10 emails per invoice per UTC day, 30 per user per hour across workspaces, 20 per workspace per UTC day while it is on the Free plan or a trial and sends through the Hoursmith sender, and 100 per workspace per hour. A spent budget is a 429 and nothing is sent. Write scope; Owner/Admin/Manager. Idempotency-Key required (a replay never re-sends).
Authorization
BearerAuth Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.
In: header
Path Parameters
Invoice id.
Header Parameters
Caller-generated UUID/ULID. Same key + same body within 24h replays the original response; money writes are additionally idempotent at the domain level for that key.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/send" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "status": "sent", "sendError": "string", "type": "invoice", "to": [ "string" ], "cc": [ "string" ], "recipientsDefaulted": true, "markedSent": true, "invoice": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "number": "string", "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "status": "DRAFT", "paymentStatus": "unpaid", "currency": "string", "total": "string", "amountPaid": "string", "balanceDue": "string", "issueDate": "2019-08-24", "dueDate": "2019-08-24", "sentAt": "2019-08-24T14:15:22Z", "lastSentAt": "2019-08-24T14:15:22Z", "paidAt": "2019-08-24T14:15:22Z" } }, "warnings": [ "string" ]}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}Preview an invoice or reminder email
Read-only. Renders the final subject and plain-text body the client would receive (private invoice link and bank details replaced by placeholders), the sender, attachments, default recipients, every address on file for the client, and readyToSend + problems. Nothing is minted or written. Read scope; Owner/Admin/Manager.
Email a payment reminder
Emails a payment reminder with the invoice PDF for a SENT invoice (409 otherwise). Does not change the invoice. Requires the overdueReminders plan feature (402). Every recipient must already be on file for the invoice's client (billing email, client email or a client contact); any other address is rejected with 422 — add it as a client contact in Hoursmith first. Omitted `to` uses the client's default billing recipient, exactly as the app pre-fills it. A provider failure returns 200 with status `failed` and `sendError`, and the invoice is unchanged. A NOT SENT warning means nothing was delivered. A NOT CONFIRMED warning means the provider call had started (a timeout, or an answer that came too late to record): the email may have reached the recipient, so check with them before sending again. Send and remind share the app's send budget: a one-minute cooldown per invoice (send and remind share it), 10 emails per invoice per UTC day, 30 per user per hour across workspaces, 20 per workspace per UTC day while it is on the Free plan or a trial and sends through the Hoursmith sender, and 100 per workspace per hour. A spent budget is a 429 and nothing is sent. Write scope; Owner/Admin/Manager. Idempotency-Key required (a replay never re-sends).