Overview

MonkeysMail is a developer-friendly email platform for transactional and marketing sends. You can deliver via SMTP or HTTP REST, track events in real time, segment audiences, and manage sending domains for top-tier deliverability.

What you can do

Send email
- SMTP or REST (/messages/send, /messages/send/list, /messages/send/segment)
- Templates, variables, tags, metadata, attachments
Track & react
- Opens, clicks, bounces, complaints, unsubscribes (webhooks + dashboard)
Organize audiences
- Lists (static) and Segments (rule-based), deduped & subscription-aware
Measure performance
- Delivery, engagement, and failure analytics with filters and export
Deliverability controls
- Domain verification, SPF/DKIM/DMARC, TLS-RPT & MTA-STS, dedicated IPs & warm-up
Governance
- API keys with scopes, per-plan quotas, usage & billing visibility

Base URLs & Environments

Surface	URL (example)	Notes
API	`https://smtp.monkeysmail.com`	REST endpoints for sending, lists/segments, events
SMTP	`smtp.monkeysmail.com:587`	STARTTLS recommended; 465 for implicit TLS
App	`https://app.monkeysmail.com`	Dashboard, logs, analytics, templates, lists
Tracking	`https://smtp.monkeysmail.com/t/*`	Open pixel, click redirect, unsubscribe

Authentication at a glance

REST: header X-API-Key: <prefix>.<secret>
- Scopes: mail:send, mail:send:list, mail:send:segment (aliases: messages:*, wildcard *)
SMTP: username/password credentials (per domain or per subaccount)

Keep credentials server-side. Rotate keys periodically. Use environment variables, not hard-coded strings.

Send in two ways

1) REST (recommended for apps/services)

curl -X POST "https://api.monkeysmail.com/messages/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <prefix>.<secret>" \
  -d '{
    "from": { "email": "no-reply@yourdomain.com", "name": "Your App" },
    "to":   ["user@example.com"],
    "subject": "Welcome!",
    "html": "<h1>Hello</h1><p>Thanks for joining.</p>",
    "tags": ["welcome"],
    "metadata": { "userId": "u_123" }
  }'

Default mode is enqueue (fast, resilient).
Add ?mode=sync (or "mode": "sync") for immediate attempts on small, latency-sensitive sends.

2) SMTP (drop-in for existing libraries)

Host: smtp.monkeysmail.com
Port: 587 (STARTTLS) or 465 (TLS)
Auth: username/password
From: a verified domain you control

Tracking & webhooks

Opens: pixel at /t/o/{rid}.gif (HEAD counted for proxy opens)
Clicks: redirect via /t/c/{rid}?u={b64url(target)}
Unsubscribes: /t/u/{rid}?reason=...
Webhooks: get JSON posts for delivered, opened, clicked, bounced, complained, unsubscribed (configure in the dashboard). Include idempotency on your receiver.

Lists & Segments

Lists are curated sets of contacts (e.g., newsletter).
Segments are dynamic (e.g., “signed up in last 7 days AND not purchased”).
Server resolves recipients when you call /messages/send/list or /messages/send/segment; deduping and subscription state are respected.

Templates & personalization

Manage templates in the dashboard.
Send with template_id and a variables object.
Use tags and metadata to label messages for analytics and workflows.

Deliverability & domains

Verify sending domains (DNS TXT).
Configure SPF, DKIM, DMARC (recommended strict s alignment in production).
Optional MTA-STS & TLS-RPT for transport security visibility.
Dedicated IPs available; follow IP warm-up guidance before high-volume sends.

Rate limits & quotas

Starter: up to 150 message units/day (resets at 00:00 UTC).
Higher plans: monthly windows; included volume per plan.
Exceeding limits returns HTTP 429 with a resetAt timestamp so you can backoff.

A “message unit” is a unique, valid recipient across to/cc/bcc (or the resolved set for lists/segments).

Errors & conventions

JSON errors: { "error": "<code>", "message": "<detail>" }
Common statuses: 401 unauthorized, 403 forbidden (scope), 422 invalid_request, 429 rate_limited, 5xx transient
Use exponential backoff for 429/503, and respect resetAt for quotas.

Security

Store keys securely (KMS/Secrets Manager).
Never embed keys in client-side code.
Enforce least-privilege scopes and rotate regularly.
Honor unsubscribe and include clear footer links for bulk mail.

Billing & usage

Usage, plan, and overage details live in Billing & Usage (dashboard).
Webhooks/CSV exports available for internal cost & deliverability reporting.