Skip to content

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

idstringrequired
The VPS ID (vps_…).

Body

requestedMonthlyLimitintegerrequired
The new monthly limit for the account, in emails. Higher than the current limit, in steps of 1,000. At least 1000.
acknowledgePrepaidTermsbooleanrequired
Must be true. Confirms the customer accepts that the invoice is paid first and unused emails are credited after the month.

Example

POST /api/v2/vps/{id}/mail-relay/quota-requests
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.

Response 201
{
"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
idstring
ID of this purchase.
statusstring
Always pending_payment. One of pending_payment.
billingModestring
Always prepaid. One of prepaid.
periodstring
The month the limit is for, as YYYY-MM.
periodStartstring
First day of the month.
periodEndstring
Last day of the month.
currentMonthlyLimitinteger
The limit before this purchase.
requestedMonthlyLimitinteger
The limit after payment.
purchasedExtraEmailsinteger
Emails bought on top of the current limit.
totalnumber
Invoice total in currencyCode.
currencyCodestring
ISO 4217 currency code.
invoiceobject
The unpaid invoice.
idstring
The invoice ID (inv_…).
numberstring or null
The invoice number shown to the customer.
amountnumber or null
Invoice total.
currencyCodestring
ISO 4217 currency code.
dueAtstring or null
When the invoice is due.
statusstring
Invoice status, Unpaid for a new invoice.
paymentUrlstring or null
Path 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.

400The body is invalid or the requested limit is not above the current one. code is invalid_mail_relay_quota_request.
401Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404The VPS was not found. code is vps_not_found.
409No 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).
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500The invoice could not be created. Try again later.