Email

Invoices, credit memos, sales receipts and estimates can be emailed to customers through the API and MCP, with the PDF attached. Sending is a governed write like any other.

Send a document

curl -X POST https://api.evenbead.com/v1/documents/<document id>/email \
  -H "Authorization: Bearer $EVENBEAD_KEY" \
  -H "Idempotency-Key: email-inv-1042-1" \
  -H "Content-Type: application/json" \
  -d '{"message": "Thanks for your order."}'

to defaults to the customer's email on file. You can pass another address, up to five cc addresses and a short message.
Estimates use POST /v1/estimates/<id>/email. MCP tools: email_document, email_estimate.
Add "dry_run": true to see the sender, recipients, subject, attachment size and policy verdict. Nothing is queued.
The response is the queued email with status queued. It goes out within a minute, subject to the rate limits below. Follow its delivery with GET /v1/email/outbox/<id> (list_emails, get_email): queued, sending, sent, failed or suppressed.
The Idempotency-Key makes a retry safe. Repeating the request returns the same email and does not send a second one.

Agents and approvals

An agent needs the propose scope and the X-Agent-Model header, as for any write. Its email waits as pending_approval (a proposal) when any of these apply:

Reason	When
`over_threshold`	The document total is above the agent's posting threshold
`new_recipient`	A To or Cc address is not the customer's email on file
`first_email`	Nothing has been emailed to this customer before

A person, or a supervising agent with the approve scope, approves (POST /v1/email/outbox/<id>/approve) or rejects it with a reason (/reject). No one approves their own email. The requester or an admin can cancel an email that has not been sent (/cancel). An admin can queue a failed email again (/retry). Every step is recorded in the company's audit log, and so is the delivery result.

Sender and replies

Mail comes from noreply@evenbead.com, with your company's name as the sender name. Set these with POST /v1/email/settings (admin scope) or the update_email_settings tool:

display_name: the sender name, if it should differ from the company name.
reply_to: your own address. Customers' replies go there. Without it, replies have nowhere to go, so set it.
security_notices_to: where Evenbead sends a notice when a new API key is created, or an accounting firm is granted or loses access.

Payment reminders

Reminders are off until a company turns them on, with reminders_enabled: true and reminder_days, for example [3, 10, 30] (days after the due date; negative numbers mean before it). Each step is sent once per open invoice, with the invoice attached, and only the latest step that is due. Turning reminders on never sends a backlog of old steps. Every reminder carries a one-click unsubscribe link. A customer who uses it stops receiving reminders from that company, but still receives invoices. GET /v1/email/suppressions lists the addresses that are not emailed.

Limits

To protect the shared mail server, sending is capped per hour for the whole service and per company. Emails over a cap wait and go out later. They are not dropped. A company with 200 emails already waiting gets 429 rate_limited until the queue drains. Temporary failures are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. A recipient the receiving server rejects as unknown is marked failed, and that address is not emailed again.

The full list of operations is under email in the API reference.