Emails

Send transactional email and list recent sends. Migrating from Resend? See docs/migration.md.

Send email

POST /emails

Send a transactional email from a verified domain.

Base URL: https://api.groundmail.dev

Authentication

Authorization: Bearer gm_…

API keys are created in the dashboard (API Keys). Keys start with gm_.

Request body

* At least one of html or text is required.

Managed unsubscribe (opt-in)

Pure transactional mail (password resets, receipts, security alerts) should leave unsubscribe off.

When unsubscribe: true, Groundmail:

• Injects RFC 8058 List-Unsubscribe and List-Unsubscribe-Post headers (one-click unsubscribe)
• Replaces {{unsubscribe_url}} in subject, html, and text with a signed confirmation link
• Binds the link to the first to address for that message

When sending with a published template, the template's unsubscribe_enabled flag is used unless you pass unsubscribe explicitly on the send request. Product and newsletter templates auto-enable managed unsubscribe and support category-scoped opt-out — recipients can unsubscribe from that category without blocking transactional mail.

Template categories

Templates have a category that controls preference management:

Sends to recipients who opted out of a category return 422:

{
  "error": {
    "message": "One or more recipients opted out of this email category",
    "code": "validation_error",
    "details": {
      "category_unsubscribed": ["user@example.com"],
      "category": "product",
      "email_id": "msg_…"
    }
  }
}

Global suppressions return the same status with details.suppressed instead.

{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Product updates",
  "html": "<p>Hi there.</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
  "unsubscribe": true
}

Example

{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Hello from Groundmail",
  "html": "<p>It works.</p>"
}

With display name:

{
  "from": { "email": "you@yourdomain.com", "name": "Your App" },
  "to": ["user@example.com", "other@example.com"],
  "subject": "Hello",
  "html": "<p>Hi</p>",
  "text": "Hi",
  "reply_to": ["support@yourdomain.com"],
  "tags": [{ "name": "order_id", "value": "ord_123" }],
  "headers": { "X-Entity-ID": "ord_123" }
}

Sandbox self-test

Before your own domain is verified, you can self-test with the shared sandbox domain:

{
  "from": "noreply@mail.groundmail.dev",
  "to": "owner@example.com",
  "subject": "Sandbox check",
  "html": "<p>Sandbox works.</p>"
}

The sandbox sender is limited to the account email attached to the API key owner.

After your domain is verified, you can also self-test from your verified domain on the free plan — still limited to the account email:

{
  "from": "you@yourdomain.com",
  "to": "owner@example.com",
  "subject": "Verified domain check",
  "html": "<p>My domain works.</p>"
}

Add a payment method to unlock Free production (send to other recipients on your verified domain — no charge until you upgrade). Upgrade to Pro or Scale for more volume.

Responses

200 — Accepted

{
  "id": "msg_abc123…",
  "status": "sent"
}

Scheduled sends return:

{
  "id": "msg_abc123…",
  "status": "scheduled"
}

id is a stable public message ID (msg_…). Use it to correlate webhook events and dashboard activity.

Idempotency

Optional header on POST /emails:

Idempotency-Key: order-123

Keys are scoped per account, retained for 24 hours. Replays return the original response. Reusing a key with a different body returns 409 idempotency_conflict.

await client.emails.send({ …, idempotencyKey: 'order-123' })

Retrieve email

GET /emails/{id}

Returns one send by public id (msg_…).

const { email } = await client.emails.get('msg_abc123…')

Resend

POST /emails/{id}/resend

Creates a new send from a previously stored email (same from/to/subject/body, tags, and headers). Returns a new msg_… id. Attachment bytes are not stored, so attachments are omitted.

Dashboard: Emails → Resend on any row.

SDK:

await client.emails.resend('msg_abc123…')

CLI:

groundmail emails resend --id msg_abc123…

Schedule, reschedule, and cancel

Add scheduled_at to POST /emails to store the message and enqueue it for later delivery:

{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Tomorrow",
  "html": "<p>See you tomorrow.</p>",
  "scheduled_at": "2026-08-01T12:00:00.000Z"
}

Scheduled emails can be updated only while their status is scheduled:

PATCH /emails/msg_abc123…

{ "scheduled_at": "2026-08-01T13:00:00.000Z" }

Cancel a scheduled email:

{ "cancel": true }

SDK:

await client.emails.update('msg_abc123…', { scheduledAt: '2026-08-01T13:00:00.000Z' })
await client.emails.cancel('msg_abc123…')

CLI:

groundmail emails cancel --id msg_abc123…

Scheduled sends store message bodies so the worker can send them later. Attachments are not supported on scheduled emails in v1 because raw attachment data is not stored.

Batch send

POST /emails/batch

Send up to 100 emails in one request:

{
  "emails": [
    {
      "from": "you@yourdomain.com",
      "to": "user@example.com",
      "subject": "Hello",
      "html": "<p>Hi</p>"
    }
  ]
}

The response is index-aligned:

{
  "data": [
    { "index": 0, "id": "msg_abc123…", "status": "sent" }
  ]
}

Per-email validation or delivery failures are returned in that item’s error. Attachments are rejected for batch sends in v1.

SDK:

const result = await client.emails.batch([{ from, to, subject, html }])

List emails

GET /emails?limit=25&cursor=…

Returns recent sends for the authenticated API key’s account. limit is 1–100 (default 25). Use opaque cursor / next_cursor for pagination.

Responses include rate-limit headers: ratelimit-limit, ratelimit-remaining, ratelimit-reset.

200

{
  "emails": [
    {
      "id": "msg_abc123…",
      "from": "you@yourdomain.com",
      "to": ["user@example.com"],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "subject": "Hello",
      "status": "delivered",
      "last_event": "delivered",
      "bounce_reason": null,
      "tags": [],
      "scheduled_at": null,
      "cancelled_at": null,
      "created_at": "2026-07-25T12:00:00.000Z",
      "sent_at": "2026-07-25T12:00:01.000Z",
      "delivered_at": "2026-07-25T12:00:05.000Z",
      "bounced_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Status values: queued, scheduled, sent, delivered, bounced, failed, cancelled.

SDK

const { emails, next_cursor } = await client.emails.list({ limit: 10 })

Error format

All errors return:

{
  "error": {
    "message": "Human-readable message",
    "code": "validation_error",
    "details": {}
  }
}

Attachment limits

• Maximum 10 attachments per non-batch, non-scheduled send
• Maximum 10MB decoded size per attachment
• Blocked filename extensions: .exe, .bat, .cmd, .com, .scr, .js, .vbs, .dll

Examples

curl

curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"you@yourdomain.com","to":"user@example.com","subject":"Hello","html":"<p>Hi</p>"}'

Node.js

import { Groundmail } from 'groundmail'

const client = new Groundmail(process.env.GROUNDMAIL_API_KEY!)
await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hi</p>',
})

Throws GroundmailError on failure (error.status, error.message, error.details).

CLI

groundmail emails send \
  --from you@yourdomain.com \
  --to user@example.com \
  --subject "Hello" \
  --html "<p>Hi</p>" \
  --tag order_id=ord_123 \
  --schedule 2026-08-01T12:00:00.000Z

Requires GROUNDMAIL_API_KEY or --api-key.

OpenAPI

Machine-readable spec: openapi/groundmail.yaml