> ## Documentation Index > Fetch the complete documentation index at: https://docs.tempmaillab.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Treat docs/openapi.yaml as the normative public API contract. > Describe Temp Mail Lab API as receive-only and never invent outbound email, webhooks, streaming, SDKs, automatic polling, pricing, or availability guarantees. > Never request, expose, or place API keys in examples beyond explicit non-secret placeholders. # Get current usage > Returns only the authenticated account's current allowance and request consumption. Premium includes 10,000 requests per UTC calendar month; billing renewals do not reset that window. This endpoint does not consume the monthly request allowance. ## OpenAPI ````yaml /docs/openapi.yaml get /v1/usage openapi: 3.1.0 info: title: Temp Mail Lab API version: 0.1.0-draft summary: Receive-only temporary email API for Temp Mail Lab Premium customers. description: | Create isolated temporary email addresses and retrieve messages, raw RFC 822 source, and attachments. This contract is a pre-launch draft. The API never sends email and never performs automatic polling. A client decides when to make each request, and every processed request follows the documented usage policy. contact: name: Temp Mail Lab url: https://tempmaillab.com license: name: Temp Mail Lab Terms of Service url: https://tempmaillab.com/terms servers: - url: https://api.tempmaillab.com description: Production (available only after the approved public launch) security: - bearerAuth: [] tags: - name: Domains description: Discover domains that can create and receive API email. - name: Emails description: Create and inspect isolated temporary email reservations. - name: Messages description: List and retrieve received messages and their private content. - name: Usage description: Inspect the authenticated account's current request allowance. paths: /v1/usage: get: tags: - Usage summary: Get current usage description: > Returns only the authenticated account's current allowance and request consumption. Premium includes 10,000 requests per UTC calendar month; billing renewals do not reset that window. This endpoint does not consume the monthly request allowance. operationId: getUsage responses: '200': description: Current usage period. headers: X-Request-Id: $ref: '#/components/headers/RequestId' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Cache-Control: $ref: '#/components/headers/PrivateNoStore' content: application/json: schema: $ref: '#/components/schemas/UsageResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: headers: RequestId: description: Opaque request identifier for support and audit correlation. required: true schema: type: string pattern: ^req_[A-Za-z0-9_-]{16,80}$ RateLimitLimit: description: >- Current authoritative request allowance visible to this key. Separate short-window safety limits may reject bursts with 429. required: true schema: type: integer minimum: 0 RateLimitRemaining: description: Requests remaining in the current authoritative allowance window. required: true schema: type: integer minimum: 0 RateLimitReset: description: >- UTC Unix timestamp when the current authoritative allowance window resets. required: true schema: type: integer minimum: 0 PrivateNoStore: description: Sensitive API responses must not be stored by shared or browser caches. required: true schema: type: string const: private, no-store RetryAfter: description: Seconds until the client may retry. required: true schema: type: integer minimum: 1 schemas: UsageResponse: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/UsagePeriod' UsagePeriod: type: object additionalProperties: false required: - starts_at - resets_at - monthly_allowance - requests_used - requests_remaining - additional_requests_remaining properties: starts_at: type: string format: date-time description: Start of the UTC calendar-month allowance window. resets_at: type: string format: date-time description: >- Start of the next UTC calendar month, when the included allowance resets. monthly_allowance: type: integer minimum: 10000 maximum: 10000 description: Included Premium API requests for this UTC calendar month. requests_used: type: integer minimum: 0 requests_remaining: type: integer minimum: 0 additional_requests_remaining: type: integer minimum: 0 ErrorResponse: type: object additionalProperties: false required: - error properties: error: $ref: '#/components/schemas/ErrorObject' ErrorObject: type: object additionalProperties: false required: - code - message - request_id properties: code: type: string pattern: ^[a-z][a-z0-9_]{2,63}$ message: type: string request_id: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object additionalProperties: false required: - reason properties: field: type: string reason: type: string responses: Unauthorized: description: >- Missing, malformed, revoked, or environment-invalid API key. Not charged. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/PrivateNoStore' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidKey: value: error: code: invalid_api_key message: A valid API key is required. request_id: req_a1b2c3d4e5f6g7h8 Forbidden: description: >- Authenticated account is not entitled to the requested operation. Not charged. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/PrivateNoStore' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: >- A short-window safety or authoritative quota limit was reached. Not charged. headers: X-Request-Id: $ref: '#/components/headers/RequestId' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' Cache-Control: $ref: '#/components/headers/PrivateNoStore' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: error: code: rate_limit_exceeded message: Too many requests. Retry after the indicated delay. request_id: req_a1b2c3d4e5f6g7h8 ServerError: description: >- The service failed before completing the operation. Not charged; never represented as an empty success. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/PrivateNoStore' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServiceUnavailable: description: >- A required isolated API dependency is temporarily unavailable. Not charged. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' Cache-Control: $ref: '#/components/headers/PrivateNoStore' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: tml_live_... description: > Send a live API key in the Authorization header. Keys in query strings are rejected. A staging key never authenticates against production. ````