Markdown

Inbound email API

Updated Nov 17, 20263 min read

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:

HTTP
Authorization: Bearer gm_...

Overview

Inbound receiving is configured on the existing domain resource:

  1. Create a domain with inbound_enabled: true or enable it later with PATCH /domains/{id}.
  2. Verify the domain (POST /domains/{id} with { "action": "verify" }).
  3. Publish the returned MX record so Groundmail can receive mail for that hostname.
  4. Subscribe to email.received webhooks 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.com already receives mail at Google Workspace, Microsoft 365, Fastmail, etc, moving the MX record will stop that provider from receiving new mail for example.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 publish
  • inbound_note — the same warning in machine-readable responses

Create a receiving domain

POST/domains

Response:

inbound_status: "pending" means inbound receiving finishes setup after verification succeeds.

Terminal
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
  }'
JSON
{
  "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

PATCH/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 configured
  • domain.inbound_status = "pending" — waiting for verification
  • domain.inbound_status = "error" + domain.inbound_error — inbound setup failed and should be retried
Terminal
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

POST/domains/{id}

If inbound_enabled is already true, verification also activates inbound receiving and returns:

  • inbound_configured
  • inbound_pending
  • inbound_error
JSON
{ "action": "verify" }

List received emails

GET/received-emails

Optional query params:

  • limit
  • cursor
  • domain — receiving domain name
  • in_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.

Terminal
curl https://api.groundmail.dev/received-emails?domain=inbound.example.com \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY"
JSON
{
  "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

GET/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.

Terminal
curl https://api.groundmail.dev/received-emails/inb_abc123 \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY"
JSON
{
  "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.

JSON
{
  "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:

  • id is the sent email's id: pass it to GET /emails/{id} for its delivery status.
  • tags are 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.
  • tenant is the tenant's external_id when the email was sent as a tenant, else null.
  • 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 null when 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.

JSON
"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
}
Terminal
curl "https://api.groundmail.dev/received-emails?in_reply_to_email=msg_6f1c0e2a93d4b7" \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY"

SDK

TypeScript
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

Terminal
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_abc123

OpenAPI

Machine-readable spec: OpenAPI spec

Was this page helpful?