Emailing an invoice

POST /v1/invoices/{id}/send — requires invoices:write. Takes no request body. The recipient is always the invoice’s own stored customerEmail and cannot be overridden. That is what stops the endpoint from being an open relay. Creating an invoice never emails anyone; this call is the only thing that does.

200 OK

{
  "invoiceId": "CcvnBwRQaKY1rXSMLrbYe",
  "sentTo": "buyer@example.com",
  "sentAt": "2026-07-09T12:05:00.000Z",
  "sendCount": 1,
  "sendsRemaining": 2,
  "maxSends": 3
}

curl -X POST https://api.taberna.io/v1/invoices/CcvnBwRQaKY1rXSMLrbYe/send \
  -H 'Authorization: Bearer tbrn_live_…'

const res = await fetch(
	`https://api.taberna.io/v1/invoices/${invoiceId}/send`,
	{
		method: 'POST',
		headers: { Authorization: `Bearer ${process.env.TABERNA_API_KEY}` },
	},
);
if (!res.ok) {
	const { error, code, retryAfterSeconds } = await res.json();
	// `code` is the branchable signal here, not the status.
	throw new Error(`${code}: ${error} (retry in ${retryAfterSeconds ?? '—'}s)`);
}

res = requests.post(
	f"https://api.taberna.io/v1/invoices/{invoice_id}/send",
	headers={"Authorization": f"Bearer {api_key}"},
)
if not res.ok:
	body = res.json()
	raise RuntimeError(f"{body.get('code')}: {body['error']}")

The three limits

Sending is capped at three independent levels. Any one of them can refuse a call.

Level	Limit
Per invoice	3 sends in total
Per invoice	5 minutes minimum between sends
Per store	100 invoice emails per rolling 24 hours
Platform-wide	5,000 per rolling 24 hours, reported as a temporary pause

These are server-configurable, so treat the numbers as current defaults rather than a contract. The shapes — a small per-invoice allowance, a cooldown, and a store-level daily budget — are the part to design against.

The email object on an invoice reflects per-invoice state only. It cannot tell you that the store’s daily budget or the platform ceiling is what will refuse the next send, so canSend: true is a necessary condition, not a guarantee.

The rate-limit envelope

This is the one endpoint whose error body differs from the rest of the API. Every failure the mailer produces carries three fields:

{
  "error": "This invoice was emailed less than 5 minutes ago. Try again in 4 minutes.",
  "code": "rate_limited",
  "retryAfterSeconds": 214
}

code is one of not_found, not_sendable, rate_limited, send_failed.
retryAfterSeconds is always present, and null when the block is not a cooldown you can wait out (an exhausted per-invoice allowance, for example).
When retryAfterSeconds is set, the same value is mirrored in a Retry-After header.

Status	`code`	When
`400`	`not_sendable`	The invoice is not `open`, or has no stored `customerEmail`
`404`	`not_found`	No such invoice for this key’s store
`429`	`rate_limited`	A per-invoice cap, a per-invoice cooldown, a per-store 24-hour cap, or a platform-wide pause
`502`	`send_failed`	The email provider rejected the send. The attempt does not count against the allowance — safe to retry.

A request rejected before it reaches the mailer answers with the plain { "error": … } shape instead, with no code and no retryAfterSeconds: a malformed {id} is 400 { "error": "Invalid request data" }, and a well-formed id that does not decode is 404 { "error": "Invoice not found" }. Read code defensively.

Read the allowance instead of probing

Every invoice payload — from create, retrieve and list — carries an email object, so you never need a 429 to discover you are blocked.

Field	Meaning
`sendCount`	Sends made so far for this invoice
`sendsRemaining`	How many are left before the per-invoice cap
`maxSends`	The per-invoice cap
`lastSentAt`	Timestamp of the last send, or `null`
`cooldownUntil`	When the minimum-interval cooldown lifts, or `null`
`canSend`	Whether a send would be accepted right now
`blockedReason`	A human-readable reason when `canSend` is `false`, otherwise `null`

Check email.canSend before calling the send endpoint rather than treating a 429 as your signal. It costs nothing — the field is on the invoice you already have.

const invoice = await api(`/v1/invoices/${invoiceId}`);

if (!invoice.email.canSend) {
	// blockedReason is already phrased for a human.
	return { sent: false, reason: invoice.email.blockedReason };
}

await api(`/v1/invoices/${invoiceId}/send`, { method: 'POST' });

A merchant can send the same email from the dashboard, against the same allowance. See Invoices from the dashboard for what the customer receives.

Get started

Charging a customer

Getting paid

Reference

Emailing an invoice

The three limits

The rate-limit envelope

Read the allowance instead of probing

​The three limits

​The rate-limit envelope

​Read the allowance instead of probing

The three limits

The rate-limit envelope

Read the allowance instead of probing