Buy a higher monthly mail relay limit
POST /api/v2/vps/{id}/mail-relay/quota-requests
Creates an invoice for a higher mail relay limit for the account in the current month. The higher limit applies once the invoice is paid. Extra emails you do not use are credited to the account after the month ends. requestedMonthlyLimit is the new total. It must be higher than the current limit and a multiple of 1,000. The price is quota.pricing on GET /api/v2/vps/{id}/mail-relay, per 1,000 extra emails. Only one unpaid quota invoice can be open. Another request returns 409 mail_relay_quota_purchase_conflict with that invoice.
Authentication: An API key with the scope write:billing. About keys and scopes
Request
Path parameters
idstringrequiredThe VPS ID (
vps_…).Body
requestedMonthlyLimitintegerrequiredThe new monthly limit for the account, in emails. Higher than the current limit, in steps of 1,000. At least 1000.
acknowledgePrepaidTermsbooleanrequiredMust be
true. Confirms the customer accepts that the invoice is paid first and unused emails are credited after the month.Example
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/quota-requests" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "requestedMonthlyLimit": 100000, "acknowledgePrepaidTerms": true }'Responses
201 The invoice was created. The higher limit waits for payment.
{ "id": "d9dc8efa-c281-477d-86ef-758dd54a9a51", "status": "pending_payment", "billingMode": "prepaid", "period": "2026-11", "periodStart": "2026-11-01", "periodEnd": "2026-11-30", "currentMonthlyLimit": 15000, "requestedMonthlyLimit": 100000, "purchasedExtraEmails": 85000, "total": 425, "currencyCode": "SEK", "invoice": { "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3", "number": "202600123", "amount": 425, "currencyCode": "SEK", "dueAt": "2026-11-09T00:00:00.000Z", "status": "Unpaid", "paymentUrl": "/billing?invoice=202600123" }}Response fields
idstringID of this purchase.
statusstringAlways
pending_payment. One of pending_payment.billingModestringAlways
prepaid. One of prepaid.periodstringThe month the limit is for, as
YYYY-MM.periodStartstringFirst day of the month.
periodEndstringLast day of the month.
currentMonthlyLimitintegerThe limit before this purchase.
requestedMonthlyLimitintegerThe limit after payment.
purchasedExtraEmailsintegerEmails bought on top of the current limit.
totalnumberInvoice total in
currencyCode.currencyCodestringISO 4217 currency code.
invoiceobjectThe unpaid invoice.
idstringThe invoice ID (
inv_…).numberstring or nullThe invoice number shown to the customer.
amountnumber or nullInvoice total.
currencyCodestringISO 4217 currency code.
dueAtstring or nullWhen the invoice is due.
statusstringInvoice status,
Unpaid for a new invoice.paymentUrlstring or nullPath in the client area where the invoice can be paid.
Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The body is invalid or the requested limit is not above the current one. code is invalid_mail_relay_quota_request. |
| 401 | Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | The VPS was not found. code is vps_not_found. |
| 409 | No invoice was created. code is mail_relay_quota_purchase_conflict. Either an unpaid quota invoice is already open (invoice, with recovery.action pay_outstanding_invoice). Or the VPS has no sending IP yet or the price could not be read (recovery.action retry_after). |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | The invoice could not be created. Try again later. |