Integrate DoMail into your automation bots or QA pipeline. No scraping required.
Every path is relative to this server. The project README documents each response in full.
Domains
GET
/api/v1/domains
Lists the active domains.
curl http://localhost:3000/api/v1/domains
POST
/api/v1/domains
Registers a domain, or re-activates one that is already present.
curl -X POST http://localhost:3000/api/v1/domains \
-H "Content-Type: application/json" \
-d '{"domain": "mail.yourdomain.com"}'
DELETE
/api/v1/domains/:domain
Removes a domain.
curl -X DELETE http://localhost:3000/api/v1/domains/mail.yourdomain.com
Mailbox
POST
/api/v1/mailbox/generate
Creates a new random address, or one with a custom prefix.
curl -X POST http://localhost:3000/api/v1/mailbox/generate \
-H "Content-Type: application/json" \
-d '{"prefix": "qa-test", "domain": "domail.internal"}'
GET
/api/v1/mailbox/:address
Lists the messages in a mailbox, including detected OTP codes. Pass ?limit= to cap the page.
curl http://localhost:3000/api/v1/mailbox/user-8f3a@domail.internal
DELETE
/api/v1/mailbox/:address
Deletes every message in a mailbox.
curl -X DELETE http://localhost:3000/api/v1/mailbox/user-8f3a@domail.internal
Messages
GET
/api/v1/message/:id
Fetches one message in full: text, HTML, verification links and OTP code. Marks it as read.
curl http://localhost:3000/api/v1/message/MESSAGE_UUID
GET
/api/v1/message/:id/raw
Sends the original RFC822 / MIME source as plain text.
curl http://localhost:3000/api/v1/message/MESSAGE_UUID/raw
DELETE
/api/v1/message/:id
Deletes a single message.
curl -X DELETE http://localhost:3000/api/v1/message/MESSAGE_UUID
Realtime
GET
/api/v1/stream/:address
Server-Sent Events: one event per message that lands, instead of polling.
curl -N http://localhost:3000/api/v1/stream/user-8f3a@domail.internal
Inbound
POST
/api/v1/inbound
Inbound email webhook for a Cloudflare Worker or an RFC822 / MIME MTA.
curl -X POST http://localhost:3000/api/v1/inbound \
-H "Content-Type: message/rfc822" \
--data-binary @raw_email.eml
Send x-domail-secret once DOMAIL_SECRET is set, and x-domail-recipient when the message carries no usable recipient.
The response reports sizeBytes against the mailbox quota and evicted, the number of older messages dropped to make room. A message too large for an empty mailbox comes back 413 with the numbers.
Testing
POST
/api/v1/simulate
Stores a test email built from JSON fields, so you can exercise a flow without a real sender.
curl -X POST http://localhost:3000/api/v1/simulate \
-H "Content-Type: application/json" \
-d '{"to": "user-8f3a@domail.internal", "text": "Your code is 839201"}'
Storage
GET
/api/v1/stats
Counts stored messages, active domains and mailboxes in use, plus totalBytes on disk and the per-mailbox quota (DOMAIL_MAILBOX_QUOTA_MB, 50 MB by default).
curl http://localhost:3000/api/v1/stats
Operations
GET
/healthz
Liveness probe for a process manager or load balancer. Needs no secret and reports counters only, never message contents.
curl http://localhost:3000/healthz