Receive mail on a verified Groundmail domain, get email.received webhooks, and retrieve full inbound messages with attachments.
Base URL: https://api.groundmail.dev
Auth:
Authorization: Bearer gm_...Overview
Inbound receiving is configured on the existing domain resource:
- Create a domain with
inbound_enabled: trueor enable it later withPATCH /domains/{id}. - Verify the domain (
POST /domains/{id}with{ "action": "verify" }). - Publish the returned MX record so Groundmail can receive mail for that hostname.
- Subscribe to
email.receivedwebhooks or poll/received-emails.
Groundmail stores:
- the inbound message headers/bodies
- attachment metadata on list responses
- full attachment base64 data on retrieve responses
Every received email is scanned for spam: spam_score (higher is more likely spam; most clean mail is under 5) and spam_status (clean, suspicious or spam; null when not scanned). A domain can flag or drop spam above its own threshold: see Content scanning.
On pay as you go, each received email counts toward your monthly emails the same as a sent one. On Free, received emails don't count.
Important MX conflict note
Inbound receiving requires changing the domain hostname's MX record to Groundmail.
That means:
- if
example.comalready receives mail at Google Workspace, Microsoft 365, Fastmail, etc, moving the MX record will stop that provider from receiving new mail forexample.com - the safest pattern is usually a dedicated subdomain such as
inbound.example.com
Every domain detail/create response includes:
inbound_records— the MX record to publishinbound_note— the same warning in machine-readable responses
Create a receiving domain
/domainsResponse:
inbound_status: "pending" means inbound receiving finishes setup after verification succeeds.
curl -X POST https://api.groundmail.dev/domains \
-H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "inbound.example.com",
"inbound_enabled": true
}'{
"domain": {
"id": "d_123",
"name": "inbound.example.com",
"status": "pending",
"created_at": "2026-07-26T00:00:00.000Z",
"verified_at": null,
"open_tracking": false,
"click_tracking": false,
"tls_mode": "opportunistic",
"inbound_enabled": true,
"inbound_status": "pending",
"inbound_error": null
},
"records": [
{
"type": "TXT",
"host": "_groundmail.inbound.example.com",
"value": "groundmail-verify=...",
"purpose": "Domain ownership"
}
],
"inbound_records": [
{
"type": "MX",
"host": "inbound.example.com",
"priority": 10,
"value": "mx.groundmail.dev",
"purpose": "Inbound receiving"
}
],
"inbound_note": "Inbound receiving requires pointing this hostname's MX record to Groundmail. That conflicts with any existing mailbox provider on the same hostname, so use a dedicated subdomain such as inbound.example.com when Google Workspace or Microsoft 365 should keep handling your main mailboxes."
}Enable inbound on an existing domain
/domains/{id}If the domain is already verified, Groundmail immediately activates inbound receiving for that hostname.
Relevant fields:
domain.inbound_status = "active"— inbound receiving is configureddomain.inbound_status = "pending"— waiting for verificationdomain.inbound_status = "error"+domain.inbound_error— inbound setup failed and should be retried
curl -X PATCH https://api.groundmail.dev/domains/inbound.example.com \
-H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "inbound_enabled": true }'Verify the domain
/domains/{id}If inbound_enabled is already true, verification also activates inbound receiving and returns:
inbound_configuredinbound_pendinginbound_error
{ "action": "verify" }List received emails
/received-emailsOptional query params:
limitcursordomain— receiving domain namein_reply_to_email— only replies to this sent email (msg_…); see Replies to emails you sent
Response:
List responses omit attachment data and null out message bodies to keep payloads smaller.
curl https://api.groundmail.dev/received-emails?domain=inbound.example.com \
-H "Authorization: Bearer $GROUNDMAIL_API_KEY"{
"received_emails": [
{
"id": "inb_abc123",
"domain_id": "d_123",
"domain_name": "inbound.example.com",
"status": "received",
"rcpt_to": "sales@inbound.example.com",
"mail_from": "sender@example.org",
"from": "Sender <sender@example.org>",
"to": ["sales@inbound.example.com"],
"cc": [],
"subject": "Question about pricing",
"spam_status": "clean",
"spam_score": 0.9,
"bounced": false,
"received_with_ssl": true,
"message_id": "<abc@example.org>",
"in_reply_to": null,
"references": [],
"in_reply_to_email": null,
"attachment_count": 1,
"attachments": [
{
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size": 48291
}
],
"text_body": null,
"html_body": null,
"auto_submitted": null,
"received_at": "2026-07-26T12:00:00.000Z",
"created_at": "2026-07-26T12:00:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}Retrieve a received email
/received-emails/{id}Received emails are kept for your plan's data retention window (7 days on Free, 90 on pay as you go, up to 1 year on Dedicated), then return 404 not_found. To keep them longer, store email.received webhooks in your own database.
Response:
Attachments are base64 encoded.
curl https://api.groundmail.dev/received-emails/inb_abc123 \
-H "Authorization: Bearer $GROUNDMAIL_API_KEY"{
"received_email": {
"id": "inb_abc123",
"domain_id": "d_123",
"domain_name": "inbound.example.com",
"status": "received",
"rcpt_to": "sales@inbound.example.com",
"mail_from": "sender@example.org",
"from": "Sender <sender@example.org>",
"to": ["sales@inbound.example.com"],
"cc": [],
"subject": "Question about pricing",
"spam_status": "clean",
"spam_score": 0.9,
"bounced": false,
"received_with_ssl": true,
"message_id": "<abc@example.org>",
"in_reply_to": null,
"references": [],
"in_reply_to_email": null,
"attachment_count": 1,
"attachments": [
{
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size": 48291,
"data": "JVBERi0xLjQKJ..."
}
],
"text_body": "Hello there!",
"html_body": "<p>Hello there!</p>",
"auto_submitted": null,
"received_at": "2026-07-26T12:00:00.000Z",
"created_at": "2026-07-26T12:00:00.000Z"
}
}Forward to a URL
Send a domain's mail to your own endpoint as the raw message, forward an address to a teammate, or drop it: see Email routing. The domain fields inbound_forward_url and inbound_forward_secret still work and set the domain's catch-all route to Send to a URL.
email.received webhook
Subscribe a webhook endpoint to email.received with POST /webhooks.
Webhook deliveries include metadata only, not full attachment data:
Retrieve the full message from /received-emails/{id} when you need bodies or attachment bytes.
{
"type": "email.received",
"created_at": "2026-07-26T12:00:01.000Z",
"data": {
"email_id": "inb_abc123",
"to": ["sales@inbound.example.com"],
"from": "Sender <sender@example.org>",
"subject": "Question about pricing",
"status": "received",
"rcpt_to": "sales@inbound.example.com",
"cc": [],
"message_id": "<abc@example.org>",
"in_reply_to": null,
"references": [],
"in_reply_to_email": null,
"spam_status": "clean",
"spam_score": 0.9,
"attachment_count": 1,
"attachments": [
{
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size": 48291
}
],
"received_at": "2026-07-26T12:00:00.000Z"
}
}Replies to emails you sent
When someone replies to an email you sent through Groundmail, and the reply reaches one of your inbound domains (for example because you sent with reply_to: "support@inbound.example.com"), Groundmail links the reply to the email it answers. The match uses the reply's In-Reply-To header, then its References, against the Message-IDs of emails your account sent.
A linked reply has in_reply_to_email on the received email and on the email.received webhook:
idis the sent email's id: pass it toGET /emails/{id}for its delivery status.tagsare the tags you sent it with, so you can route the reply to your own record (an order, a ticket, a user) without storing Groundmail ids first.tenantis the tenant'sexternal_idwhen the email was sent as a tenant, elsenull.- It is a copy taken when the reply arrived, so it is still there after the sent email passes your plan's data retention.
- It is
nullwhen the reply matches none of your sent emails, including replies that arrived before this was available.
List every reply to one sent email:
In the dashboard, a linked reply opens in Inbound as a conversation: the email you sent, any other replies to it, then this reply.
"in_reply_to_email": {
"id": "msg_6f1c0e2a93d4b7",
"subject": "Your receipt from Acme (#1042)",
"from": "billing@acme.com",
"to": ["maya@northwind.io"],
"sent_at": "2026-10-28T23:02:00.000Z",
"tags": [{ "name": "order_id", "value": "1042" }],
"tenant": null
}curl "https://api.groundmail.dev/received-emails?in_reply_to_email=msg_6f1c0e2a93d4b7" \
-H "Authorization: Bearer $GROUNDMAIL_API_KEY"SDK
import { Groundmail } from 'groundmail'
const client = new Groundmail(process.env.GROUNDMAIL_API_KEY!)
await client.domains.create({
name: 'inbound.example.com',
inbound_enabled: true,
})
await client.domains.verify('inbound.example.com')
const { received_emails } = await client.receivedEmails.list({
domain: 'inbound.example.com',
})
const one = await client.receivedEmails.get(received_emails[0].id)
// Every reply to one email you sent
const replies = await client.receivedEmails.list({ inReplyToEmail: 'msg_6f1c0e2a93d4b7' })CLI
groundmail domains add inbound.example.com --inbound true
groundmail domains verify inbound.example.com
groundmail domains update inbound.example.com --inbound true
groundmail received-emails list --domain inbound.example.com
groundmail received-emails list --in-reply-to-email msg_6f1c0e2a93d4b7
groundmail received-emails get inb_abc123OpenAPI
Machine-readable spec: OpenAPI spec