Outbound Email
Get Outbound Config
Section titled “Get Outbound Config”GET /domains/{name}/outboundReturns outbound sending configuration, anti-spam settings, and metrics for a domain.
Response
Section titled “Response”| Field | Type | Description |
|---|---|---|
name | string | Domain name |
outbound_tier | string | shared or dedicated |
outbound_status | string | active or suspended |
outbound_daily_limit | integer | Max emails/day (0 = unlimited) |
outbound_monthly_limit | integer | Max emails/month (0 = unlimited) |
outbound_sent_today | integer | Emails sent today |
outbound_sent_month | integer | Emails sent this month |
outbound_enforcement | string | soft (allowed and counted; limits do not reject) or hard (rejects when limits are exceeded) |
bounce_count | integer | Bounces this period |
complaint_count | integer | Complaints this period |
bounce_rate | float | Bounce rate (%) |
complaint_rate | float | Complaint rate (%) |
ses_verified | boolean | Whether domain is verified with the mail provider |
warmup_profile | string | Warm-up category: fast, standard, conservative, or established |
spike_max_multiplier | float | Max ratio vs 7-day avg before spike protection triggers (0 = disabled) |
Example
Section titled “Example”curl https://api.emboux.com/domains/example.com/outbound \ -H "Authorization: Bearer {API_KEY}"Update Outbound Config
Section titled “Update Outbound Config”PUT /domains/{name}/outboundUpdate outbound limits, tier, enforcement, or status for a domain.
Request Body
Section titled “Request Body”All fields are optional — only include the fields you want to change.
| Field | Type | Description |
|---|---|---|
outbound_daily_limit | integer | Max emails/day |
outbound_monthly_limit | integer | Max emails/month |
outbound_tier | string | shared or dedicated |
outbound_enforcement | string | soft or hard |
outbound_status | string | active or suspended |
warmup_profile | string | fast, standard, conservative, or established (master only; a customer token gets 403). Any other value returns 422. |
spike_max_multiplier | float | Spike detection multiplier (master only, 0 = disabled) |
Example
Section titled “Example”curl -X PUT https://api.emboux.com/domains/example.com/outbound \ -H "Authorization: Bearer {API_KEY}" \ -H "Content-Type: application/json" \ -d '{"outbound_daily_limit": 500, "outbound_monthly_limit": 10000}'Increment Outbound Counter
Section titled “Increment Outbound Counter”POST /domains/{name}/outbound/incrementCheck quotas and increment the outbound counter by 1. Called by the Policy Daemon for each outgoing email.
Returns allowed: true if the email can be sent. If a soft cap is exceeded, still returns allowed: true with a reason field indicating the exceeded limit.
Response
Section titled “Response”| Field | Type | Description |
|---|---|---|
name | string | Domain name |
outbound_sent_today | integer | Updated daily counter |
outbound_sent_month | integer | Updated monthly counter |
allowed | boolean | Whether the email is allowed |
reason | string? | Reason if blocked or soft-exceeded |
Possible reasons:
outbound_suspended— domain outbound is suspended (hard cap)outbound_suspended_soft— suspended but allowed (soft cap)daily_limit_exceeded— daily limit hit (hard cap)daily_limit_exceeded_soft— daily limit hit but allowed (soft cap)monthly_limit_exceeded— monthly limit hit (hard cap)monthly_limit_exceeded_soft— monthly limit hit but allowed (soft cap)
Domain Verification
Section titled “Domain Verification”Initiate Verification
Section titled “Initiate Verification”POST /domains/{name}/verifyInitiates domain verification with the configured mail provider (Mailgun). Returns the DNS records you need to configure on your DNS provider. For a step-by-step walkthrough, see Send as your own domain.
Available to both master and customer tokens. Customer tokens may only verify domains they own (the API filters by partner_ref; a 404 is returned for any other domain). Master tokens additionally support verifying root/parent domains that are not present in the local domain table — useful when you only registered subdomains.
Outbound email is blocked until the domain is verified.
Response
Section titled “Response”| Field | Type | Description |
|---|---|---|
name | string | Domain name |
verification_token | string | Provider-specific verification value |
dkim_tokens | string[] | DKIM token identifiers |
verified | boolean | Whether already verified |
dns_records | object[] | DNS records to configure |
provider | string | Provider used (mailgun, ses) |
Each dns_records entry:
| Field | Type | Description |
|---|---|---|
type | string | TXT, CNAME, etc. |
name | string | DNS record name |
value | string | DNS record value |
Example
Section titled “Example”curl -X POST https://api.emboux.com/domains/example.com/verify \ -H "Authorization: Bearer {API_KEY}"{ "name": "example.com", "verification_token": "v=spf1 include:mailgun.org ~all", "dkim_tokens": ["krs"], "verified": true, "dns_records": [ {"type": "TXT", "name": "example.com", "value": "v=spf1 include:mailgun.org ~all"}, {"type": "TXT", "name": "krs._domainkey.example.com", "value": "k=rsa; p=MIIBIjAN..."}, {"type": "CNAME", "name": "email.example.com", "value": "mailgun.org"} ], "provider": "mailgun"}Check Verification Status
Section titled “Check Verification Status”GET /domains/{name}/verify-statusChecks the current verification status with the configured provider. If verified, automatically updates the domain status.
The {name} can be a parent domain. Verification status is propagated to all subdomains sharing the same verify domain.
Response
Section titled “Response”| Field | Type | Description |
|---|---|---|
name | string | Domain name |
verified | boolean | Overall verification status |
verification_status | string | Provider status: Pending, Success, NotStarted, etc. |
dkim_status | string | DKIM status: Pending, Success, etc. |
provider | string | Provider used |
Register Subdomain
Section titled “Register Subdomain”POST /domains/{name}/register-subdomainRegisters a subdomain that inherits verification from its parent domain. The behavior varies by provider:
- Mailgun: registers with
dkim_host_authority=true(inherits parent’s DKIM) - SES: no-op (DKIM inherited automatically)
Available to master and customer tokens (customers must own the subdomain — see /domains/.../register-subdomain for the canonical reference). The {name} must be a subdomain (3+ domain parts).
Response
Section titled “Response”Same as Verify response (VerifyResponse schema).
Provider Credentials
Section titled “Provider Credentials”Per-tenant SMTP credentials at the mail provider, wired into Postfix’s sender-dependent SASL map so each tenant’s outbound mail signs with its own provider identity (proper DKIM and Return-Path alignment).
Provision
Section titled “Provision”POST /domains/{name}/provider-credentialMaster token only. Generates a fresh credential at the provider and installs it for the domain (and every subdomain that inherits it). The plaintext password is returned once — persist it on your side if you need a copy. Re-POST to rotate.
Response 200 OK
Section titled “Response 200 OK”{ "domain": "tenant.com", "provider": "mailgun", "password": "32-char-hex", "patterns_installed": ["@tenant.com", "@sub1.tenant.com"], "sasl_path": "/etc/postfix/sasl_passwd_mailgun"}Revoke
Section titled “Revoke”DELETE /domains/{name}/provider-credentialMaster token only. Idempotent — calling on a domain with no installed credential returns 200 with patterns_removed: 0.
Deliverability Report
Section titled “Deliverability Report”GET /domains/{name}/deliverability?days=7Read-only audit of what the mail provider did with the mail sent from this domain over the last days days (1–30, default 7): how much was accepted and delivered, what failed and why, and complaints. A client token sees only its own domains; the master token sees any.
The report contains aggregates only. Recipient addresses never appear — failed deliveries are summarized by recipient domain.
Response 200 OK
Section titled “Response 200 OK”{ "domain": "tenant.ganemo.com", "authority_domain": "ganemo.com", "provider": "mailgun", "days": 7, "period_start": "2026-10-27T20:00:00+00:00", "period_end": "2026-11-03T20:00:00+00:00", "counts": { "accepted": 646, "delivered": 630, "failed_permanent": 6, "failed_temporary": 10, "complained": 0, "unsubscribed": 0, "opened": 0, "clicked": 0 }, "suppressed": 1, "delivered_pct": 97.52, "hard_bounce_pct": 0.77, "complaint_pct": 0.0, "failures": [ {"severity": "temporary", "reason": "generic", "code": 452, "message": "4.2.2 The recipient's inbox is out of storage space…", "count": 10}, {"severity": "permanent", "reason": "bounce", "code": 550, "message": "5.1.1 The email account that you tried to reach does not exist…", "count": 4}, {"severity": "permanent", "reason": "suppress-complaint", "code": 607, "message": "Not delivering to a user who marked your messages as spam", "count": 1} ], "failed_recipient_domains": [{"domain": "gmail.com", "count": 12}, {"domain": "hotmail.com", "count": 3}], "events_scanned": 11250, "truncated": false}| Field | Meaning |
|---|---|
authority_domain | Where the provider files the events. A subdomain that inherits DKIM from its parent is reported from the parent, filtered to this domain’s sender. |
delivered_pct, hard_bounce_pct, complaint_pct | Percentages over accepted; null when nothing was accepted. hard_bounce_pct excludes the provider’s own suppressions. |
suppressed | Messages the provider refused to attempt because the recipient had previously bounced, complained or unsubscribed (suppress-* reasons). |
truncated | The provider’s event log was too large to read in one call; counts are a lower bound. Ask for fewer days. |
| Status | When |
|---|---|
404 | The domain does not exist or does not belong to the token. |
501 | The domain’s provider does not offer delivery reports (SES). |
502 | The mail provider did not answer. |
Anti-Spam Protections
Section titled “Anti-Spam Protections”EmBoux applies several layers of protection to every outbound email. Since 2026-11-05 the sending policy is enforced at send time on ports 587 and 465. If the policy service does not respond, the email is still sent (the check fails open).
Which layers reject depends on the domain’s outbound_enforcement mode:
soft: the email is allowed and recorded. It counts toward limits and overage billing, but limits do not reject it.hard: the email is rejected when a limit is exceeded.
| Layer | Check | Action |
|---|---|---|
| Domain verification | Root domain not verified and no verified parent (any mode) | 550 5.7.1 Domain not verified. Configure DNS records first. |
| Suppression list | Recipient previously bounced or complained (any domain) | hard: 550 5.1.1 reject. soft: recorded only |
| Domain suspended | Outbound status = suspended | hard: 452 4.2.2 reject. soft: allowed |
| Warm-up | Domain exceeds its progressive daily cap | 452 4.2.2 Warm-up limit reached (<N>/day, profile=<profile>). Domain active for <D> days. (when warm-up applies) |
| Spike detection | Today’s volume is far above the 7-day rolling average | hard: 452 4.2.2 reject. soft: allowed |
| Hourly throttle | Exceeded ~1/6 of daily limit in one hour | hard: 452 4.2.2 reject. soft: allowed |
| Daily limit | Exceeded daily sending limit | hard: 452 4.2.2 reject. soft: allowed and counted |
| Monthly limit | Exceeded monthly sending limit | hard: 452 4.2.2 reject. soft: allowed and counted |
The suppression list is global: a bounce on one domain protects all other domains from sending to the same bad address. See SMTP errors for what each rejection means and how to fix it.
Warm-up Profiles
Section titled “Warm-up Profiles”Each domain has a warm-up category. New domains default to standard: they start with a base cap of 50 emails/day that grows every day according to the profile.
| Profile | Growth | Time to 200/day | Time to 1,000/day | Time to 10,000/day |
|---|---|---|---|---|
fast | 1.8x/day | 3 days | 6 days | 10 days |
standard | 1.1x/day | 15 days | 32 days | 56 days |
conservative | 1.05x/day | 29 days | 62 days | 109 days |
established | No ramp | n/a | n/a | n/a |
established has no warm-up ramp. Use it for senders with a sending history, for example customers who already send mail, or who migrate their lists from another server.
The warm-up ends naturally when it reaches the domain’s outbound_daily_limit. Only these four values are accepted for warmup_profile (PUT /domains/{name}/outbound returns 422 for anything else). In Odoo the category is changed on the domain form by the EmBoux Manager group. The date of the first send cannot be edited.
Guillotine (Auto-Suspension)
Section titled “Guillotine (Auto-Suspension)”For domains in hard mode, a domain is automatically suspended when:
- Bounce rate > 0.5% — protects your provider reputation
- Complaint rate > 0.1% — complaints are treated more severely than bounces
Automatic suspension does not apply to soft domains. Thresholds are configurable via environment variables (BOUNCE_RATE_THRESHOLD, COMPLAINT_RATE_THRESHOLD).
Webhooks
Section titled “Webhooks”EmBoux receives bounce and complaint events from each mail provider via provider-specific webhook endpoints. All webhooks feed the same shared logic: update domain counters, add recipients to the global suppression list, and trigger the guillotine if thresholds are exceeded.
SES Webhook
Section titled “SES Webhook”POST /webhooks/sesReceives SNS notifications from Amazon SES. No authentication required (SNS cannot send Bearer tokens).
Handles: SubscriptionConfirmation, Bounce, Complaint.
Mailgun Webhook
Section titled “Mailgun Webhook”POST /webhooks/mailgunReceives Mailgun event webhooks. Validated via HMAC-SHA256 signature (if MAILGUN_WEBHOOK_SIGNING_KEY is configured).
Handles: failed / bounced → Bounce, complained → Complaint.
Reset Counters
Section titled “Reset Counters”Reset Daily
Section titled “Reset Daily”POST /outbound/reset-dailySaves today’s send count into a 7-day rolling history (used for spike detection), then resets outbound_sent_today to 0 for all domains. Called by the midnight UTC cron job. Master token required.
Response
Section titled “Response”| Field | Type | Description |
|---|---|---|
reset_count | integer | Number of domains reset |
Reset Monthly
Section titled “Reset Monthly”POST /outbound/reset-monthlyFreezes current monthly counters (for billing), then resets all monthly counters to 0. Master token required.
Response
Section titled “Response”| Field | Type | Description |
|---|---|---|
frozen | object[] | Per-domain frozen values before reset |
reset_count | integer | Number of domains reset |
Each frozen entry contains: name, partner_ref, outbound_sent_month, outbound_monthly_limit, bounce_count, complaint_count, bounce_rate, complaint_rate.