Skip to main content

​
API responses and privacy

Customer endpoints return only information needed to use your account. These rules apply to API-key requests and the customer dashboard. Operational details remain in administrator diagnostics; API keys cannot access those diagnostics.

​
Response envelope

Use success and the HTTP status to handle the outcome. A successful send means queued, not delivered. Save trackingId and use the tracking endpoints for subsequent status, delivery, bounce, open and click counts. The sending receipt contains only: Internal delivery-provider names/IDs, tenant routing, queue/job IDs, relay assignments, worker retry policy, storage keys and raw upstream responses are not part of the customer contract. Do not depend on undocumented fields.

​
JSON field names

API-owned JSON fields use camelCase: accountId, planId, createdAt, invoiceId and verificationStatus. This applies to successful responses and validation field names. Status and enum values such as pending_payment keep their documented spelling. HTTP header names and path parameter placeholders are not JSON field names. List responses that include pagination use:
hasNext and hasPrev are optional; some endpoints return only page and total counts. Mailbox listing still returns an array directly in data. This update changes field names, not the existing list wrappers or pagination behaviour. Older releases returned page_size, total_items, total_pages, has_next and has_prev in plan, invoice and chat pagination. Read the camelCase names above when updating an integration. SDK models may expose language-native properties (for example Python’s page_size) while reading camelCase JSON. User-defined maps, message content and fields belonging to an external protocol retain their original keys. They are not recursively renamed. The official SDKs apply the same rule when decoding responses: API-owned fields are read by their camelCase names, legacy snake_case aliases are accepted and then removed, and camelCase wins when both spellings are present. Unknown keys, user-defined maps and third-party payloads are preserved unchanged. The raw HTTP response remains exactly as documented above.

​
Tracking and activity

Message lists retain the tracking identifier, subject, sender address, recipients, delivery and engagement counts, statuses and timestamps. Individual events retain their ID, type, recipient address, clicked URL and occurrence time. Provider event IDs, provider message IDs, event sources and raw delivery metadata are omitted. Customer activity pages and CSV/NDJSON exports expose the same reduced details. Metadata is limited to customer-useful descriptions, amounts, units, domain setup state and public tracking identifiers. Infrastructure errors and worker state are not exported.

​
Other customer endpoints

  • Mailbox records contain your mailbox identity and status, without backend provider names or provider mailbox IDs.
  • Client-connection settings still include the public SMTP/IMAP/POP3 hostnames, ports, security mode and username required to configure your mail app.
  • Account status contains plan and sending-credit information, without database or Redis health diagnostics.
  • Domain search returns quote identifiers, domain names, customer prices, currency, expiry and availability. Supplier identities, wholesale prices and supplier error messages are omitted. Use the quote ID when purchasing.
  • Payment-method identifiers remain available because checkout needs the chosen payment method. DNS-provider detection describes your domain’s public DNS provider so you can complete DNS setup; it does not identify the email backend.
  • Invoice metadata retains customer billing amounts and domain-registration progress, without raw gateway responses or internal processing leases.
  • File-upload receipts contain fileName, contentType and sizeBytes. publicUrl is returned only when public attachment hosting is configured; internal storage endpoints and object keys are not returned.
Newly issued API keys and mailbox passwords are intentional one-time outputs. Save them securely. Contact-sync cursors remain available to the applications that require them. Stored encrypted credentials, credential hashes and service secrets are never returned.

​
Errors

Errors use the appropriate HTTP status and a safe message:
A validation failure (422) also lists the field that failed and the text to fix it. Every value is a plain string:
SDK errors expose the same details: the HTTP status, the envelope statusCode (and legacy status_code), the errors validation map, the API’s own code when present, and the x-request-id header. Names are language-native, such as apiCode/api_code and requestId/request_id. Service failures do not expose upstream response bodies, configuration variable names or internal URLs. If a send outcome is uncertain, check message activity before retrying to avoid a duplicate message. Keep the response request ID when contacting support.

​
Migrating existing integrations

Replace reads of upstream.trackingId with data.result.trackingId. Remove references to provider, providerCode, jobId, queuedBy, routingMode, maxAttempts, raw event metadata and upload storage keys. Use documented public IDs and status fields. Ordinary send requests can omit envelopeSender; the API aligns the envelope with the selected mailbox or the route’s managed bounce address. Caller input does not override that selection. See Sending email for sender selection and fallback behavior.