#Email

Send transactional email from your own domain. Email must be enabled for your account.

#1. Add and verify a sending domain

bash

curl https://api.mittis.ai/v1/domains \
  -H "Authorization: Bearer $MITTIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.example.com" }'

The domain starts pending and the response lists the DNS records to publish. Publish them at your DNS host, then check:

bash

curl -X POST https://api.mittis.ai/v1/domains/$DOMAIN_ID/verify \
  -H "Authorization: Bearer $MITTIS_API_KEY"

A 200 does not mean verified: read status (verified, pending while records propagate, or failed). Pending domains are re-checked automatically for 72 hours, and a domain.verified webhook fires when the status changes. Unverified domains are released after 7 days (domain.expired). A previously verified domain whose records later break moves to degraded (domain.degraded) and cannot send until you fix DNS.

Public mailbox providers (like gmail.com), disposable domains, IP addresses and single-label hosts are rejected. A domain can belong to one account only.

#2. Send

bash

curl https://api.mittis.ai/v1/emails \
  -H "Authorization: Bearer $MITTIS_API_KEY" \
  -H "Idempotency-Key: estimate-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Riverside Plumbing <jobs@mail.example.com>",
    "to": "dana@example.com",
    "subject": "Your estimate is ready",
    "html": "<p>Tap to review and approve.</p>",
    "tags": ["estimate"],
    "metadata": { "jobId": "job_1042" }
  }'

from must be on a verified domain. to, cc and bcc take an address or an array: up to 50 recipients in total.
Provide html, text, or both (1 MB each). tags (up to 10) and metadata (up to 20 string pairs) are stored with the email, and externalRef is returned as-is.
The email is queued and returned immediately with status queued.
Recipients skipped because of an earlier bounce, complaint or unsubscribe are marked suppressed and are not billed. If every recipient is suppressed the email is returned failed.
Not available yet: attachments, templates, scheduling and batch sending.

#3. Follow it

Email status is queued, sent, delivered, partially_delivered, bounced or failed. Read one with GET /v1/emails/{id} and its per-recipient timeline with GET /v1/emails/{id}/events, or subscribe to webhooks: email.sent, email.delivered, email.deferred, email.bounced, email.failed, email.opened, email.clicked, email.complained and email.unsubscribed. See the event catalog.

#Suppressions

Hard bounces, spam complaints and unsubscribes are added to your suppression list automatically. Manage it with GET /v1/email-suppressions and DELETE /v1/email-suppressions/{address}.

#Testing

sk_test_ keys send nothing and bill nothing. For end-to-end lifecycle events with a live key, the reference for POST /v1/emails documents reserved sandbox recipient addresses that produce real webhooks without delivering or billing.