Skip to main content

Domains & Mailboxes

Every mailbox lives under a verified custom domain.

Add a domain​

curl -X POST https://api.purpletoadmail.com/api/v1/domains \
  -H "Authorization: Bearer pt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "yourdomain.com"}'

The response includes the DNS records you must add:

  • MX — tells the world where to deliver mail.
  • SPF — authorizes PurpleToad Mail to send on your behalf.
  • DKIM — signs outgoing mail cryptographically.
  • DMARC — tells receivers how to handle authentication failures.

Verify DNS​

PurpleToad Mail polls DNS automatically. You can also trigger a check for the mail records:

curl -X POST https://api.purpletoadmail.com/api/v1/domains/{domain_id}/verify-dns \
  -H "Authorization: Bearer pt_live_your_key_here"

There is also a separate TXT ownership-verification endpoint at /api/v1/domains/{domain_id}/verify for the initial domain-ownership check.

Create a mailbox​

curl -X POST https://api.purpletoadmail.com/api/v1/mailboxes \
  -H "Authorization: Bearer pt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "your-domain-id",
    "local_part": "hello",
    "password": "StrongMailboxPass1!",
    "display_name": "Hello Team",
    "quota_mb": 512
  }'

Only domain_id and local_part are required. If you omit password, PurpleToad Mail generates one and returns it once. A custom password must contain at least 8 characters, including uppercase, lowercase, numeric, and special characters.

Connect a mail app​

The dashboard provides a practical client setup guide with an Apple configuration profile, mobile-friendly instructions, and copyable IMAP/SMTP settings. Thunderbird may also discover the standard XML endpoint automatically.

Open a mailbox in the dashboard and select Client Setup. Apple users can download a configuration profile. Thunderbird and other IMAP clients can copy the displayed server settings.