cybernethicc-terminal
4%
Booting neural core...
Booting neural core...
dispatch.cybernethicc.comDispatch is a high-performance transactional email service. Send emails via HTTP API or SMTP relay, manage sending domains, track delivery status, and handle bounces automatically.
Sending API
https://dispatch.cybernethicc.com/api/v1SMTP Server
dispatch.cybernethicc.com:2525 / 2587Content Type
application/jsonGetting Started
/send endpoint.Sending works with your Dispatch credentials: Basic Auth on the HTTP /send endpoint, or SMTP AUTH on the relay. Everything else (domains, credentials, templates, webhooks, suppressions, logs) is managed in the Portal; the endpoints below for those need a signed-in Portal session and are not available with credentials or API keys.
Use the username and password from your Dispatch credentials. Base64-encode username:password and pass it in the Authorization header.
curl https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/send \
-u "[email protected]:your-password" \
-H "Content-Type: application/json" \
-d '{"from":"[email protected]","to":["[email protected]"],"subject":"Hello","html_body":"<h1>Hi</h1>"}'The Portal itself calls the management endpoints with the short-lived token of your signed-in session. Sending with a session token needs an active subscription; sending with credentials keeps working during the grace period after a renewal is due.
curl https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/send \
-H "Authorization: Bearer eyJhbGciOi..." \
-H "Content-Type: application/json" \
-d '{ ... }'Connect to dispatch.cybernethicc.com on port 2525 or 2587 with STARTTLS, and authenticate with AUTH PLAIN using your credential. Port 465 (implicit TLS) is not offered. The username already ends in @dispatch.cybernethicc.com; use it exactly as shown.
Host: dispatch.cybernethicc.com
Port: 2525 or 2587
Security: STARTTLS
Auth: PLAIN
Username: {credential_username} (already ends in @dispatch.cybernethicc.com)
Password: {credential_password}All endpoints are prefixed with /api/v1. Replace {tenant_id} with your tenant UUID.
/dispatch/tenants/{id}/sendSend a single email
/dispatch/tenants/{id}/send-bulkSend up to 100 emails in one request
/dispatch/tenants/{id}/domainsAdd a sending domain
/dispatch/tenants/{id}/domainsList domains with DNS records
/dispatch/tenants/{tid}/domains/{did}/verifyVerify domain DNS records
/dispatch/tenants/{tid}/domains/{did}/dns-setupAuto-configure DNS via provider
/dispatch/tenants/{tid}/domains/{did}Remove a domain
/dispatch/tenants/{id}/templatesCreate an email template
/dispatch/tenants/{id}/templatesList all templates
/dispatch/tenants/{tid}/templates/{tmpl_id}Update a template
/dispatch/tenants/{tid}/templates/{tmpl_id}Delete a template
/dispatch/tenants/{id}/credentialsCreate SMTP/API credential
/dispatch/tenants/{id}/credentialsList credentials
/dispatch/tenants/{tid}/credentials/{cred_id}Revoke a credential
/dispatch/tenants/{id}/suppressionsAdd email to suppression list
/dispatch/tenants/{id}/suppressionsList suppressed emails
/dispatch/tenants/{tid}/suppressions/{sup_id}Remove from suppression list
/dispatch/tenants/{id}/webhooksRegister a webhook endpoint
/dispatch/tenants/{id}/webhooksList webhooks
/dispatch/tenants/{tid}/webhooks/{wh_id}Delete a webhook
/dispatch/tenants/{id}/emailsList sent emails (paginated)
/dispatch/tenants/{id}/emails/{log_id}Get email detail with body
/dispatch/tenants/{id}/emails/{log_id}Delete an email log entry
/dispatch/plansList available plans
/dispatch/tenantsList your tenants
/dispatch/tenants/{id}Get tenant details with usage
/dispatch/tenants/{id}Update tenant settings
/dispatch/tenants/{id}/usageGet usage stats and rates
/dispatch/tenants/{id}/queueView email queue summary
/user/dns-providersConnect a DNS provider (Cloudflare, Route53, GCP)
/user/dns-providersList connected DNS providers
/user/dns-providers/{id}/zonesList DNS zones from provider
/user/dns-providers/{id}Disconnect a DNS provider
Send a single email via the HTTP API. Supports raw HTML, templates with variable substitution, file attachments (base64-encoded), and the master email template wrapper.
/dispatch/tenants/{tenant_id}/send| Field | Type | Required | Description |
|---|---|---|---|
| from | string | Required | Sender email address (must be on a verified domain) |
| to | string[] | Required | Array of recipient email addresses |
| subject | string | Required | Email subject line (overridden by template if template_id is set) |
| html_body | string | Optional | HTML email body (ignored if template_id is set) |
| text_body | string | Optional | Plain text fallback body |
| template_id | string | Optional | Template UUID or slug. Overrides html_body and subject. |
| template_variables | object | Optional | Key-value pairs to substitute {{variable}} placeholders in the template |
| use_master_template | boolean | Optional | Wrap html_body with the portal master email template (default: false) |
| attachments | array | Optional | File attachments (see attachment object below) |
| Field | Type | Description |
|---|---|---|
| filename | string | Original filename (e.g. "report.pdf") |
| content_type | string | MIME type (e.g. "application/pdf", "image/png") |
| content | string | Base64-encoded file content |
| inline | boolean | If true, attach inline with Content-ID for use in HTML as cid:<content_id> |
| content_id | string | Content-ID for inline images (without angle brackets) |
curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/send \
-u "[email protected]:your-password" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Welcome to our platform",
"html_body": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
"text_body": "Welcome! Thanks for signing up."
}'{
"data": { ... },
"message": "1 email(s) queued for delivery"
}curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/send \
-u "[email protected]:your-password" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "unused (overridden by template)",
"template_id": "welcome-email",
"template_variables": {
"user_name": "John Doe",
"company": "Acme Inc"
}
}'curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/send \
-u "[email protected]:your-password" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Your Invoice #1234",
"html_body": "<p>Please find your invoice attached.</p>",
"attachments": [
{
"filename": "invoice-1234.pdf",
"content_type": "application/pdf",
"content": "JVBERi0xLjQK..."
}
]
}'Rate Limiting & Quotas
Send up to 100 emails in a single API call. Each message goes through individual quota, rate-limit, and suppression checks. The response includes per-message success or failure details.
/dispatch/tenants/{tenant_id}/send-bulkcurl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/send-bulk \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Hello Alice",
"html_body": "<p>Hi Alice!</p>"
},
{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Hello Bob",
"html_body": "<p>Hi Bob!</p>"
}
]
}'{
"data": {
"sent": 2,
"failed": 0,
"results": [
{ "index": 0, "success": true, "message": "1 recipient(s) queued" },
{ "index": 1, "success": true, "message": "1 recipient(s) queued" }
]
},
"message": "2 email(s) queued, 0 failed"
}Create reusable email templates with variable placeholders. Templates can be referenced by UUID or slug when sending emails. Variables use double-brace syntax: {{variable_name}}.
/dispatch/tenants/{tenant_id}/templatescurl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/templates \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "Welcome Email",
"slug": "welcome-email",
"subject": "Welcome, {{user_name}}!",
"html_body": "<h1>Hello {{user_name}}</h1><p>Welcome to {{company}}.</p>",
"text_body": "Hello {{user_name}}, welcome to {{company}}."
}'Variables are auto-extracted from the subject and html_body. You can also explicitly define them with the variables field as a JSON object.
/dispatch/tenants/{tenant_id}/templates/{template_id}curl -X PUT https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/templates/{template_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"subject": "Welcome aboard, {{user_name}}!",
"html_body": "<h1>Welcome {{user_name}}</h1><p>Updated template content.</p>"
}'/dispatch/tenants/{tenant_id}/templates/dispatch/tenants/{tenant_id}/templates/{template_id}Add sending domains to your tenant and verify ownership via DNS TXT records. Once verified, emails sent from that domain are automatically signed with DKIM.
curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/domains \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{ "domain": "yourdomain.com" }'{
"data": {
"domain": { "id": "...", "domain": "yourdomain.com", "verified": false, ... },
"dns_records": [
{
"record_type": "TXT",
"host": "_cybdispatch.yourdomain.com",
"value": "cybdispatch-verify-abc123...",
"purpose": "Domain verification"
},
{
"record_type": "TXT",
"host": "dispatch._domainkey.yourdomain.com",
"value": "v=DKIM1; k=rsa; p=MIIBIj...",
"purpose": "DKIM signing"
},
{
"record_type": "TXT",
"host": "yourdomain.com",
"value": "v=spf1 include:dispatch.cybernethicc.com ~all",
"purpose": "SPF - authorize sending servers"
},
{
"record_type": "TXT",
"host": "_dmarc.yourdomain.com",
"value": "v=DMARC1; p=quarantine; rua=mailto:[email protected]",
"purpose": "DMARC policy"
},
{
"record_type": "MX",
"host": "dispatch.yourdomain.com",
"value": "10 dispatch.cybernethicc.com",
"purpose": "Bounce handling return path"
}
]
}
}After adding the DNS records, call the verify endpoint. Dispatch checks for the TXT record at _cybdispatch.yourdomain.com via DNS.
curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/domains/{domain_id}/verify \
-H "Authorization: Bearer {token}"{
"data": { "verified": true, "domain": { ... } }
}| Record | Type | Host | Purpose |
|---|---|---|---|
| Verification | TXT | _cybdispatch.yourdomain.com | Proves domain ownership |
| DKIM | TXT | dispatch._domainkey.yourdomain.com | Email signature verification |
| SPF | TXT | yourdomain.com | Authorizes sending servers |
| DMARC | TXT | _dmarc.yourdomain.com | Alignment policy for SPF + DKIM |
| Return Path | MX | dispatch.yourdomain.com | Reserved for bounce handling (recommended, not required to send) |
Connect your DNS provider (Cloudflare, AWS Route 53, or Google Cloud DNS) and Dispatch creates the SPF, DKIM and DMARC records and verifies the domain for you.
# Cloudflare
curl -X POST https://portal.cybernethicc.com/api/v1/user/dns-providers \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"provider": "cloudflare",
"label": "My Cloudflare",
"token": "your-cloudflare-api-token"
}'
# AWS Route 53
curl -X POST https://portal.cybernethicc.com/api/v1/user/dns-providers \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"provider": "route53",
"label": "My AWS",
"access_key": "AKIAIOSFODNN7EXAMPLE",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"region": "us-east-1"
}'
# Google Cloud DNS
curl -X POST https://portal.cybernethicc.com/api/v1/user/dns-providers \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"provider": "gcp",
"label": "My GCP",
"service_account_json": "{...}",
"project_id": "my-gcp-project"
}'curl https://portal.cybernethicc.com/api/v1/user/dns-providers/{provider_id}/zones \
-H "Authorization: Bearer {token}"{
"data": [
{ "id": "abc123", "name": "yourdomain.com" },
{ "id": "def456", "name": "otherdomain.com" }
]
}curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/domains/{domain_id}/dns-setup \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"provider_id": "{dns_provider_uuid}",
"zone_id": "abc123",
"zone_name": "yourdomain.com",
"spf_action": "append",
"dmarc_action": "create",
"dmarc_rua_email": "[email protected]"
}'spf_action: append (add include to existing SPF),overwrite, orskip.
dmarc_action: create,update, orskip.overwrite and update work on Cloudflare; on Route 53 and Google Cloud DNS use append and create.
Instead of copying records by hand, connect your DNS provider once and let Dispatch publish the DKIM, SPF and DMARC records for a sending domain. Supported providers: Cloudflare, Amazon Route 53 and Google Cloud DNS.
append, overwrite or skip; DMARC create, update or skip.append, so an SPF record you already use for other senders is extended, not replaced./api/v1/user/dns-providersConnected providers (portal session)
/api/v1/user/dns-providers/{provider_id}/zonesZones of a provider
/api/v1/dispatch/tenants/{id}/domains/{domain_id}/dns-setupPublish the records
{
"provider_id": "5b0f...",
"zone_id": "a1b2c3...",
"zone_name": "yourdomain.com",
"spf_action": "append",
"dmarc_action": "create"
}Create API credentials for authenticating HTTP API and SMTP requests. The password is only shown once at creation time -- store it securely.
curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/credentials \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{ "label": "Production API" }'{
"data": {
"id": "uuid-here",
"username": "[email protected]",
"password": "Xq7vR2...",
"label": "Production API",
"smtp_host": "dispatch.cybernethicc.com",
"smtp_port": 2525,
"note": "Save this password now - it will not be shown again."
}
}Important
The password is returned only once when the credential is created. It is stored as a hash and cannot be retrieved later. If lost, revoke the credential and create a new one.
curl https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/credentials \
-H "Authorization: Bearer {token}"curl -X DELETE https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/credentials/{credential_id} \
-H "Authorization: Bearer {token}"Lock sending to your own servers. Add an address (203.0.113.9) or a range (203.0.113.0/24). As soon as the first entry exists, SMTP connections from any other address are refused, even with valid credentials (the HTTP API is not restricted by this list). Remove the last entry to go back to unrestricted sending.
/api/v1/dispatch/tenants/{id}/allowed-ipsList (portal session)
/api/v1/dispatch/tenants/{id}/allowed-ipsAdd an IP or CIDR
/api/v1/dispatch/tenants/{tenant_id}/allowed-ips/{ip_id}Remove
{ "cidr": "203.0.113.0/24", "label": "app servers" }The suppression list prevents emails from being sent to specific addresses. Hard bounces are automatically added to the suppression list. You can also manually add or remove entries.
curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/suppressions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"reason": "User requested removal"
}'Paginated with limit (max 100) and offset query parameters.
curl "https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/suppressions?limit=50&offset=0" \
-H "Authorization: Bearer {token}"curl -X DELETE https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/suppressions/{suppression_id} \
-H "Authorization: Bearer {token}"Automatic Suppression
Hard bounces (InvalidRecipient, BadDomain, InvalidMailbox, NoMailbox) are automatically added to the suppression list.
Register webhook endpoints to receive real-time notifications about email delivery events. Dispatch will POST event payloads to your URL when events occur.
curl -X POST https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/webhooks \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/dispatch",
"events": ["sent", "delivered", "bounced"],
"secret": "your-webhook-secret"
}'| Event | Description |
|---|---|
| sent | Email accepted and queued for delivery |
| delivered | Remote mail server confirmed delivery |
| bounced | Email bounced or delivery failed temporarily (hard and soft bounces) |
| complained | A late (out-of-band) bounce or complaint report arrived for the message |
{
"event": "bounced",
"tenant_id": "uuid-of-your-dispatch",
"timestamp": "2026-10-02T08:15:00Z",
"data": {
"recipient": "[email protected]",
"sender": "[email protected]",
"message_id": "abc123",
"bounce_classification": "InvalidRecipient",
"response": { "code": 550, "content": "User not found" }
}
}Each request carries X-Dispatch-Signature: sha256=<hex>, the HMAC-SHA256 of the raw body with your webhook secret. Compute it on your side and compare before trusting the payload.
# List webhooks
curl https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/webhooks \
-H "Authorization: Bearer {token}"
# Delete webhook
curl -X DELETE https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/webhooks/{webhook_id} \
-H "Authorization: Bearer {token}"View sent email history with delivery status tracking. Email bodies are encrypted at rest and decrypted on demand when viewing individual log entries. Log retention depends on your plan.
Paginated list of sent emails (body not included). Use page and limit (max 100) query params.
curl "https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/emails?page=1&limit=50" \
-H "Authorization: Bearer {token}"{
"data": [
{
"id": "uuid",
"message_id": "[email protected]",
"from_address": "[email protected]",
"to_addresses": ["[email protected]"],
"subject": "Welcome",
"body_size_bytes": 2048,
"has_attachments": false,
"status": "delivered",
"bounce_type": null,
"queued_at": "2026-03-29T10:00:00Z",
"delivered_at": "2026-03-29T10:00:05Z",
"bounced_at": null,
"expires_at": "2026-04-12T10:00:00Z"
}
],
"pagination": { "total": 150, "page": 1, "limit": 50, "total_pages": 3 }
}Returns the full email including decrypted body, HTML body, and bounce details.
curl https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/emails/{log_id} \
-H "Authorization: Bearer {token}"curl -X DELETE https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/emails/{log_id} \
-H "Authorization: Bearer {token}"Monitor your sending volume, delivery rates, and quota consumption for the current billing period.
curl https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/usage \
-H "Authorization: Bearer {token}"{
"data": {
"period_start": "2026-03-01T00:00:00Z",
"period_end": "2026-04-01T00:00:00Z",
"emails_sent": 4250,
"monthly_quota": 10000,
"overage_enabled": false,
"stats": { ... },
"breakdown": {
"total": 4250,
"delivered": 4100,
"hard_bounce": 50,
"soft_bounce": 80,
"complaint": 2
},
"rates": {
"delivery_rate_pct": 96,
"hard_bounce_rate_pct": 1.2,
"soft_bounce_rate_pct": 1.9,
"complaint_rate_pct": 0.047
}
}
}Enable overage to continue sending after your monthly quota is reached (additional charges apply per your plan).
curl -X PUT https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"tenant_name": "My App Emails",
"overage_enabled": true
}'Check the current email delivery queue to see pending, deferred, or retrying messages.
curl https://dispatch.cybernethicc.com/api/v1/dispatch/tenants/{tenant_id}/queue \
-H "Authorization: Bearer {token}"Messages that could not be delivered on the first attempt wait in the queue and are retried automatically. The queue summary shows what is waiting for your tenant, which helps when a recipient domain is slow or temporarily refusing mail.
/api/v1/dispatch/tenants/{id}/queueQueue summary (portal session)
The API returns standard HTTP status codes. Error responses include a message describing what went wrong.
| Status | Meaning | Common Causes |
|---|---|---|
| 400 | Bad Request | Invalid request body, recipient on suppression list, quota exceeded |
| 401 | Unauthorized | Missing or invalid authentication credentials |
| 403 | Forbidden | Tenant not active (suspended/blocked), credential mismatch |
| 404 | Not Found | Tenant, domain, template, or credential not found |
| 429 | Rate Limited | Per-minute rate limit exceeded for your plan |
| 500 | Internal Error | Server error, contact support |
{
"error": {
"code": "QUOTA_EXCEEDED",
"message": "Monthly quota exceeded (10000/10000). Enable overage or upgrade plan."
}
}Cybernethicc Dispatch API v1