Outbound Email

Get Outbound Config

GET /domains/{name}/outbound

Returns outbound sending configuration and metrics for a domain.

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 (allow + bill) or hard (reject)
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 SES

Example

curl https://mail.emboux.com/domains/example.com/outbound \
  -H "Authorization: Bearer {API_KEY}"

---

Update Outbound Config

PUT /domains/{name}/outbound

Update outbound limits, tier, enforcement, or status for a domain.

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

Example

curl -X PUT https://mail.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

POST /domains/{name}/outbound/increment

Check 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

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)

---

SES Domain Verification

Initiate Verification

POST /domains/{name}/ses-verify

Calls AWS SES VerifyDomainIdentity and VerifyDomainDkim for the domain. Returns the DNS records the customer must configure.

Outbound email is blocked until the domain is verified.

Response

Field	Type	Description
name	string	Domain name
ses_verification_token	string	TXT record value for _amazonses.{domain}
ses_dkim_tokens	string[]	3 DKIM tokens for CNAME records
ses_verified	boolean	Always false after initiation
dns_records	object[]	Pre-formatted DNS records to configure

Each dns_records entry:

Field	Type	Description
type	string	TXT or CNAME
name	string	DNS record name
value	string	DNS record value

Example

curl -X POST https://mail.emboux.com/domains/example.com/ses-verify \
  -H "Authorization: Bearer {API_KEY}"

{
  "name": "example.com",
  "ses_verification_token": "abc123...",
  "ses_dkim_tokens": ["token1", "token2", "token3"],
  "ses_verified": false,
  "dns_records": [
    {"type": "TXT", "name": "_amazonses.example.com", "value": "abc123..."},
    {"type": "CNAME", "name": "token1._domainkey.example.com", "value": "token1.dkim.amazonses.com"},
    {"type": "CNAME", "name": "token2._domainkey.example.com", "value": "token2.dkim.amazonses.com"},
    {"type": "CNAME", "name": "token3._domainkey.example.com", "value": "token3.dkim.amazonses.com"}
  ]
}

Check Verification Status

GET /domains/{name}/ses-status

Checks the current SES verification status. If both domain identity and DKIM are verified, automatically updates ses_verified = true in the database.

Response

Field	Type	Description
name	string	Domain name
ses_verified	boolean	Overall verification status
verification_status	string	SES identity status: Pending, Success, Failed, TemporaryFailure, NotStarted
dkim_status	string	SES DKIM status: Pending, Success, Failed, TemporaryFailure, NotStarted

---

SES Webhook

POST /webhooks/ses

Receives SNS notifications from Amazon SES for bounces and complaints. No authentication required (SNS cannot send Bearer tokens).

Handles:

• SubscriptionConfirmation — auto-confirms the SNS subscription
• Bounce — increments bounce_count, recalculates bounce_rate
• Complaint — increments complaint_count, recalculates complaint_rate

Guillotine: If bounce_rate > 3%, the domain’s outbound is automatically suspended.

---

Reset Counters

Reset Daily

POST /outbound/reset-daily

Resets outbound_sent_today to 0 for all domains. Called by the midnight UTC cron job. Requires master token.

Response

Field	Type	Description
reset_count	integer	Number of domains reset

Reset Monthly

POST /outbound/reset-monthly

Freezes current monthly counters (for billing), then resets all monthly counters to 0. Requires master token.

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.