DigitMailer API

Basics

Send a message POST /v1/messages

curl -X POST https://api.digitmailer.co.za/v1/messages \
  -H "Authorization: Bearer dm_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Billing <billing@yourdomain.co.za>",
    "to": ["customer@example.com"],
    "subject": "Your invoice INV-1042",
    "html": "<p>Please find your invoice attached.</p>",
    "text": "Please find your invoice attached.",
    "attachments": [
      {"filename": "INV-1042.pdf", "content_type": "application/pdf", "content_b64": "JVBERi0x..."}
    ],
    "idempotency_key": "inv-1042-first-send"
  }'

Response 202:

{"id": "0d9c1c6e-8f2a-4c1e-9c1a-2b7e8f0a1d42", "status": "queued"}

• The from domain must be verified and active on your account (see Domains below).
• Up to 500 recipients per call; each recipient counts as one email against your plan.
• html, text, or both — at least one is required.
• Attachments are base64-encoded; total message size up to 20 MB.
• idempotency_key (or an Idempotency-Key header) makes retries safe: a repeated call returns the original id with "duplicate": true.
• If some recipients are on your suppression list they are skipped and returned in a "suppressed" array.

Message status & delivery feedback GET /v1/messages/{id}

{
  "id": "0d9c1c6e-...",
  "status": "accepted",
  "recipients": [
    {"addr": "customer@example.com", "status": "delivered",
     "detail": "250 2.0.0 OK", "updated_at": "2026-08-20T21:41:43Z"}
  ],
  "opened": true, "open_count": 2, "first_opened_at": "2026-08-20T21:44:01Z",
  "events": [
    {"event": "queued", "at": "..."},
    {"event": "smtp_accepted", "detail": "5E77444DB7", "at": "..."},
    {"event": "delivered", "detail": "customer@example.com: 250 2.0.0 OK", "at": "..."},
    {"event": "opened", "at": "..."}
  ]
}

• status is the pipeline state: queued → sending → accepted (handed to the mail server) or failed.
• Per-recipient status: pending, delivered, deferred (temporary failure, retrying), bounced (rejected — detail carries the receiving server's reply), or complained (recipient reported it as spam).
• Opens are tracked via a pixel in HTML mail. Treat them as a lower bound — image blocking hides opens, and some providers prefetch images.

Domains verify before you send

Register the domain you send from, publish the DNS records we return, then verify. Sending is enabled the moment your DKIM record is live. The dashboard wizard does the same thing visually.

# Register — returns the DNS records to publish (DKIM required; SPF + DMARC recommended)
curl -X POST https://api.digitmailer.co.za/v1/domains \
  -H "Authorization: Bearer dm_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "yourdomain.co.za"}'

# Check DNS and activate
curl -X POST https://api.digitmailer.co.za/v1/domains/yourdomain.co.za/verify \
  -H "Authorization: Bearer dm_YOUR_KEY"

# List / inspect / remove
GET    /v1/domains
GET    /v1/domains/{domain}
DELETE /v1/domains/{domain}

• Domain states: pending_dns → active; a domain whose DKIM record disappears is suspended and reactivates automatically when the record returns.
• We re-check your DNS every 6 hours.

Usage GET /v1/usage?month=2026-08

{"month": 202608, "accepted": 12480, "delivered_to_postfix": 12401, "failed": 12,
 "plan": {"code": "starter", "name": "Starter", "included_emails": 50000, "overage_policy": "block"},
 "remaining": 37520}

Per-key options set when creating a key in the dashboard

Tip: create separate keys for transactional and marketing traffic so each gets the right behavior.

Suppressions automatic list hygiene

Addresses that report your mail as spam or hard-bounce (user unknown) are suppressed automatically and skipped on future sends — this protects your sender reputation.

GET    /v1/suppressions            # list: addr, reason (complaint|hard_bounce|unsubscribe|manual), detail
DELETE /v1/suppressions/{addr}     # remove an address (use with care)

Response codes