API Documentation
8 reference pages for integrating Cloud Server for Email.
REST API for application integration, SMTP relay for legacy systems, Mailgun-compatible endpoint for zero-rewrite migrations from Mailgun, webhooks for delivery event handling. Each page documents one specific surface, with the operational details and edge cases that matter in production.
The integration shape
Cloud Server for Email exposes two integration surfaces. The choice between them depends mostly on what your existing application speaks. SMTP relay is configuration-only: change DNS records and SMTP credentials, your application code does not change. REST API is for senders who want application-level features (template management, batched sends, programmatic suppression management) or webhook-driven delivery event handling.
Quick reference: minimum viable integration
The smallest possible REST integration — a transactional send with one recipient — looks like this:
POSThttps://api.cloudserverforemail.com/v1/messages
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"from": "alerts@yourdomain.com",
"to": "user@example.com",
"subject": "Welcome",
"html": "<p>Hello</p>"
}
Response is a JSON object containing the message ID, queue position, and the webhook URL where delivery events will be sent. The full request payload supports CC, BCC, custom headers, scheduled delivery, list unsubscribe headers (mandatory under RFC 8058 for any sender above 5,000/day to Gmail or Yahoo), and per-message tagging for analytics. See the Messages API documentation for the complete reference.
SMTP relay: configuration only
If your application already speaks SMTP (most CRMs, transactional flows, mail-merge tools), the integration is four DNS records and a credential change:
$ SMTP server: smtp.cloudserverforemail.com $ SMTP port: 587 (STARTTLS) or 465 (SMTPS) $ Username: smtp_YOUR_ACCOUNT_ID $ Password: YOUR_SMTP_PASSWORD
The DNS records (SPF, DKIM, DMARC, return-path subdomain) are documented in the Authentication page. Existing SMTP integrations continue working; the change is invisible to application code.
What the API does well, and what it does not
Honesty about API design helps integration go faster. The Cloud Server for Email API is built around the assumption that the operator knows email infrastructure — and it exposes more of the underlying machinery than a typical transactional email API. That is a feature for senders who want control. It is friction for senders who do not.
Where the API is genuinely good: per-message vMTA selection, programmatic suppression list management with reason codes preserved across exports, webhook event payloads that include the full delivery chain (DKIM result, SPF result, receiving server response), and an admin endpoint surface for the kind of operational work most ESPs require a support ticket to perform. The IP pool selection at send time matters more than it sounds — it lets you route by stream (transactional, marketing, cold) at the application level, instead of pre-assigning an entire account to one pool.
Where the API is intentionally minimal: there is no template builder. There is no campaign UI. There is no contact list management — that lives in MailWizz, which the API integrates with. The API is the sending and event-handling layer; the application logic above it is yours to build, or yours to use MailWizz for. Senders who want a SaaS-grade UX for everything will find the API surface narrower than they expected. Senders who want infrastructure they can integrate from a backend service will find it pleasant to work with.
Authentication patterns at a glance
Three credential types exist, with different scopes:
API_KEY — full account access, used for REST API SMTP_USER+PASS — sending only, used for SMTP relay WEBHOOK_SECRET — signing key for verifying incoming webhook payloads
The Authentication doc covers the full credential model: scoped API keys (read-only versus write), SMTP credential rotation, webhook signature verification with HMAC-SHA256, and the request signing recommendations for production deployments. Most integrations use one API key per environment (production, staging) with the appropriate scope; the practice of using a single root credential for everything is documented as an anti-pattern, not a recommendation.
Two practical recommendations matter more than the rest. First: use the webhook event stream rather than polling the message status endpoint. Webhooks deliver state changes within seconds; polling burns rate limit budget and produces stale state. Second: implement webhook retry handling. Webhook delivery is at-least-once with exponential backoff over 24 hours; idempotent event handling on your side prevents duplicate processing without losing events.
Getting started2 pages
Two pages cover the foundation. The Authentication doc walks through API key generation, the SMTP credential model, and the request signing process. The REST API Overview is the architectural map — endpoint structure, base URL conventions, error handling, pagination, and the request/response patterns that hold across all endpoints.
Core API endpoints2 pages
Two endpoints handle the work that operators actually do day-to-day. The Messages API is the send endpoint — accepts a payload, validates it, queues it for delivery through PowerMTA. The Suppressions API is the bookkeeping endpoint — adds bounce and complaint events to the suppression list, queries suppression status, and lets you export the current state. These two cover roughly 90% of the integration surface for most senders.
Events and integration2 pages
Two pages for the asynchronous side of email infrastructure. Webhooks deliver delivery events — sent, opened, bounced, complained, unsubscribed — to your application in near-real-time. The Mailgun-compatible API exists for senders migrating from Mailgun who do not want to rewrite their integration code; the endpoint surface mirrors Mailgun's so existing application code keeps working with only DNS and credential changes.
Reference2 pages
Two reference pages for the operational details that come up during integration debugging. Rate Limits documents the per-account, per-endpoint, and per-IP limits — the 429 responses you might encounter and how to handle them with proper backoff. Error Codes is the dictionary of every HTTP and application-level error the API returns, with the operational meaning of each (which errors are retryable, which require operator intervention, which indicate misconfiguration).
Frequently asked questions
How does this API differ from generic transactional email APIs?
Should I use SMTP relay or REST API?
How does the Mailgun-compatible API work?
What are the rate limits?
Are there SDKs?
Need integration help?
The reference pages cover what the API does. For specific integration questions — multi-region routing, custom webhook handlers, high-volume rate limit negotiation, migration from a specific source platform — schedule a technical assessment with our integration engineering team.
Schedule a technical assessment →