Quickstart

If you're using an AI coding agent, paste this URL into your conversation and it will have full API context to build TopMail integrations autonomously.

Use the POST /email/send endpoint to send a transactional email. Replace tm_live_abc123 with your actual API key. No domain setup is needed — emails are sent from your workspace's shared sending domain, with from_email used as the Reply-To address so replies go back to you.

curl -X POST https://api.topmail.so/api/v1/email/send \
  -H "Authorization: Bearer tm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from TopMail",
    "html": "<h1>Welcome!</h1><p>Your first email via the TopMail API.</p>",
    "from_email": "you@yourdomain.com",
    "from_name": "Your App"
  }'

{
  "data": {
    "sent": 1,
    "failed": 0,
    "skipped": 0,
    "total": 1,
    "results": [
      {
        "to": "recipient@example.com",
        "message_id": "01234567-89ab-cdef-0123-456789abcdef",
        "success": true
      }
    ]
  }
}

Use the message_id from the response to check the delivery status of your email.

curl https://api.topmail.so/api/v1/email/MSG_ID/status \
  -H "Authorization: Bearer tm_live_abc123"