Markdown

Emails

Send transactional email and list recent sends. Migrating from Resend? See Migration from Resend.

Updated Nov 17, 202616 min read

Send email from your app with Groundmail (Next.js, Node, API key). Video, with captions.

Send email

POST/emails

Send a transactional email from a verified domain.

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

curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reset-8841" \
  -d '{
    "from": "Acme <hello@mail.acme.io>",
    "to": "maya@northwind.io",
    "subject": "Reset your password",
    "html": "<p>Your code is 482913</p>"
  }'
{
  "id": "msg_794399cdfb1bfc21",
  "status": "queued"
}

Authentication

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

HTTP
Authorization: Bearer gm_…

Request body

fromstring or { email, name? }required
Exactly one address, on a verified domain: you@yourdomain.com, Name <you@yourdomain.com> or { email, name }. Put a name with special characters in double quotes ("Acme: Support" <you@yourdomain.com>), or use { email, name }. Optional when you pass sender, the template has a sender, or your team has a default sender (who it's from). When set, it wins.
senderstringoptional
A saved sender's handle or id, such as "billing". Sets from, and reply_to when you don't pass one. Ignored when from is set. An unknown sender returns 422.
tostring or string[]required
Recipient(s), each ada@example.com, Ada <ada@example.com> or "Lovelace, Ada" <ada@example.com>. Pass several as an array: each entry is exactly one address.
subjectstringrequired
Subject line
htmlstringNo*
HTML body (htmlBody / html_body aliases accepted)
textstringNo*
Plain-text body (textBody, text_body, and plain_body aliases accepted)
reply_tostring or string[]optional
Reply-to address(es) (replyTo alias accepted)
ccstring or string[]optional
CC recipient(s), written like to
bccstring or string[]optional
BCC recipient(s), written like to
tags{ name, value }[] or objectoptional
Up to 10 key/value tags stored with the email
headersobjectoptional
Custom headers; dangerous transport headers are rejected
attachmentsarrayoptional
Up to 10 files, 10MB decoded each, in a request of at most 20MB (limits); executable/script extensions are blocked. Attachment aliases filename, contentType, content, and contentId are also accepted.
scheduled_atstringoptional
ISO 8601 timestamp. Creates a scheduled email instead of sending immediately (scheduledAt alias accepted)
unsubscribebooleanoptional
Opt in to managed unsubscribe (see below). Off by default for transactional mail.
validationobjectoptional
Opt-in checks for this send. { "block_bot_signups": true } holds back addresses that look like bot sign-ups (details). Off by default.
categorystringoptional
Deprecated. Groundmail decides whether each email is transactional or product (how), so transactional and product are accepted and ignored. newsletter still sends an opt-in newsletter, for approved accounts: see Newsletter category.
tenantstringoptional
Send as one of your tenants (its external_id or id): the send uses that tenant's domains, suppression list, sending ramp and pause switch. A send from a tenant's own domain is that tenant's without it. Pay as you go and Dedicated plans; on Free it returns 403 tenants_not_enabled.

* At least one of html or text is required. from is required only when nothing else says who the email is from (below).

Who it's from

Groundmail picks the From address in this order:

  1. from (and reply_to) on the request.
  2. sender on the request: a saved sender's name, address and reply-to.
  3. The template's sender, when you send a template that has one.
  4. Your team's default sender.

With none of these, the send returns 400 asking for from. Add and manage senders under Domains › Senders in the dashboard, or with the Senders API.

Addresses with an internationalized domain (info@bücher.example) can be sent in either form: Groundmail converts the domain to its ASCII (punycode) form, info@xn--bcher-kva.example, before sending. The email record and webhooks show the converted address.

JSON
{
  "sender": "billing",
  "to": "user@example.com",
  "template": { "id": "receipt", "variables": { "amount": "$20.00" } }
}

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 templates auto-enable managed unsubscribe and support category-scoped opt-out — recipients can unsubscribe from product email without blocking transactional mail.

Template categories

Groundmail decides each template's category from its published content, and sends from it go out by that:

Category Unsubscribe behavior Sent from
transactional No category opt-out. Global suppression only. Transactional IPs
product Category-scoped opt-out, with managed unsubscribe Product IPs

A template's own category field is deprecated: it's stored and ignored. Templates and automation steps still reject newsletter with a 400 validation_error. See Transactional and product streams.

Newsletter category (by approval)

category: "newsletter" on POST /emails (or an item of POST /emails/batch) sends an opt-in newsletter. It is accepted only for accounts we approve; email support@groundmail.dev to ask. Approved newsletter email:

  • goes out from its own IPs, separate from transactional and product email, so a newsletter can never affect your sign-in codes and receipts;
  • always carries List-Unsubscribe and one-click unsubscribe (List-Unsubscribe-Post), and {{unsubscribe_url}} is filled in; unsubscribe: false is a 400 validation_error;
  • honours category opt-outs (a recipient can leave your newsletter and keep getting transactional and product email), suppressions and Groundmail validation like product email;
  • has its own daily ramp-up limit, the same size as the product limit and counted separately;
  • is paused on its own after high bounce or complaint rates, leaving transactional and product email sending.

On an account that is not approved, the send returns 403 and nothing is sent. Groundmail never sends it as another category instead:

Each email's stream (transactional, product or newsletter) and its detected_category are on GET /emails, GET /emails/{id} and webhook payloads; stream is also in the dashboard's Emails list.

Sends to recipients who opted out of a category return 422. A send for a tenant checks that tenant's opt-outs and the account-wide ones; an opt-out from one tenant's email never blocks another tenant's:

To let a recipient who re-subscribed receive that category again, remove the opt-out: see Category opt-outs.

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

JSON
{
  "error": {
    "message": "Newsletter sending isn't enabled on this account yet. Newsletter email is accepted only for approved accounts.",
    "code": "newsletter_not_enabled",
    "hint": "Send transactional or product email as usual. To send opt-in newsletters, email support@groundmail.dev to ask for approval; until then, `category: \"newsletter\"` sends are refused and nothing is sent.",
    "docs_url": "https://docs.groundmail.dev/errors#newsletter_not_enabled"
  }
}
JSON
{
  "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_…"
    }
  }
}
JSON
{
  "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

With display name:

JSON
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Hello from Groundmail",
  "html": "<p>It works.</p>"
}
JSON
{
  "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:

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:

Add a payment method to unlock Free production (send to other recipients on your verified domain). Free is never charged; you're only billed if you turn on pay as you go. Turn on pay as you go at Settings → Billing to keep sending past 3,000 a month.

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

Responses

200 — Accepted

Groundmail answers as soon as your email is checked and safely stored, and hands it to the mail server in the background, so the call doesn't wait for that hand-off. status: "queued" means exactly that: the email is accepted and on its way. Follow what happens next with GET /emails/{id} or webhooks:

  • email.delivered when the recipient's mail server accepts it;
  • status: "failed" with a bounce_reason, and an email.failed webhook, if the mail server refuses it. A refusal like that used to come back as an upstream_error on the send call; for a queued send it arrives this way instead;
  • temporary mail server problems are retried for you for about 15 minutes before an email is marked failed.

An email with attachments is handed to the mail server during the request, so its response comes back once the mail server has it, and a mail server problem is an upstream_error on the call.

Scheduled sends return:

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

A test send (a test key, gm_test_…, or only simulator addresses) adds "test": true. Nothing was delivered: its status and webhooks are simulated. See Testing.

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

Recipients held back by Groundmail validation

Before an email goes out, Groundmail validation holds back recipients that cannot receive email, so they never bounce. This is on for every account and costs nothing. A recipient is held back when:

reason Meaning
invalid_address The address cannot exist (for example ada@@example.com).
no_mail_server The domain does not exist or takes no email: no MX or A record, or a null MX.
previously_bounced The address hard-bounced (the mailbox does not exist) for a Groundmail sender in the last 90 days.
mailbox_not_found Groundmail validation already knows the mailbox does not exist.
likely_bot_signup The address looks like a bot filled it into a form. Only when the send sets validation: { "block_bot_signups": true }; see Bot sign-ups.

Disposable and role addresses (info@, support@) are never held back: they can receive email, and whether to accept them is your call. Check them up front with POST /validate. Unless a send opts in to block_bot_signups, nothing that is merely uncertain is held back, and the check never slows a send down.

When some recipients are held back, the email goes to the rest and the response lists who was held back and why:

When every to recipient is held back, nothing is sent. The API returns 422 with code: validation_error and details.held_back, a suppressed email record is created, and email.suppressed fires with held_back in its data, the same as for a suppressed recipient:

The email object (GET /emails/{id}) carries held_back too, and the dashboard's Emails page shows it. previously_bounced and mailbox_not_found draw on what Groundmail has seen across senders; an account owner can turn those two off in Settings → Suppressions. invalid_address and no_mail_server always apply.

JSON
{
  "id": "msg_abc123…",
  "status": "queued",
  "held_back": [{ "email": "ada@no-mail.example", "reason": "no_mail_server" }]
}
JSON
{
  "error": {
    "message": "Groundmail validation held back every recipient",
    "code": "validation_error",
    "details": {
      "held_back": [{ "email": "ada@no-mail.example", "reason": "no_mail_server" }],
      "email_id": "msg_…"
    }
  }
}

Idempotency

Optional header on POST /emails and POST /emails/batch:

Keys are scoped per account, retained for 24 hours. Replays return the original response and send nothing again. For a send answered queued, the replay is that same queued response even after the email has gone out: read its current status with GET /emails/{id}. Reusing a key with a different body returns 409 idempotency_conflict. Keys used with a test key are kept apart from keys used with live keys, and batch keys from single-send keys.

HTTP
Idempotency-Key: order-123
TypeScript
await client.emails.send({ …, idempotencyKey: 'order-123' })
await client.emails.batch([…], { idempotencyKey: 'digest-2026-11-02' })

Retrieve email

GET/emails/{id}

Returns one send by public id (msg_…).

Emails older than your plan's data retention window return the normal 404 not_found.

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

Delivery details

delivery shows what the recipient's mail server said about the latest delivery attempt: which server took the email, its exact reply, and whether the connection used TLS.

Field Meaning
receiving_server Hostname of the recipient's mail server that took the connection
response Its SMTP reply to the latest attempt that finished, exactly as sent: a 250 when it accepted the email, the 5xx it refused with when it bounced. A multi-line reply is joined into one line. null while there has been none
tls Whether the connection used TLS. null when the attempt didn't say
deferred_response Its reply to the latest deferral: a 4xx, such as greylisting or a rate limit. Delivery is retried automatically, and the deferral stays here after the email is delivered
deferred_at When the latest deferral happened

delivered_at minus created_at is how long the email took to land, measured from when the API accepted it to when the recipient's server replied 250.

delivery is null until an attempt reports one, for test emails, and for emails sent before 29 October 2026. List rows (GET /emails) carry it too.

To watch an email land from the terminal, live, with the server's reply and the time: groundmail emails send … --watch, or groundmail emails get <id> --watch for one you already sent. See Watch an email land.

JSON
{
  "email": {
    "id": "msg_abc123…",
    "status": "delivered",
    "created_at": "2026-10-29T12:00:00.000Z",
    "delivered_at": "2026-10-29T12:00:02.900Z",
    "delivery": {
      "receiving_server": "gmail-smtp-in.l.google.com",
      "response": "250 2.0.0 OK  1793012345 d75a77b69052e-4613a1b2c3si123456a.42 - gsmtp",
      "tls": true,
      "deferred_response": null,
      "deferred_at": null
    }
  }
}

Data retention

Groundmail keeps your email logs for a set number of days by plan, then deletes them.

Plan Logs kept
Free 7 days
Pay as you go 90 days
Dedicated Up to 1 year, set for your account

Deleted after the window: each sent email's content (subject, HTML and text bodies, headers, attachment details) and its delivery and engagement events (delivered, bounced, complained, opened, clicked), and inbound emails you received (GET /received-emails). Once deleted, GET /emails/{id} and GET /received-emails/{id} return 404 not_found, and the email no longer appears in lists, search, exports or the dashboard.

Kept: aggregate sending stats (sent, delivered, bounce and complaint counts and rates on Home, the Emails page and GET /deliverability), suppressions, templates, domains and everything else in your account.

The window counts from when the email was created. Scheduled emails are kept until they send.

Keeping history longer: subscribe a webhook to the email.* and email.received events and store each one in your own database. Webhooks deliver every event as it happens, so your copy has no time limit. Turning on pay as you go extends the window for emails that haven't been deleted yet.

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:

CLI:

TypeScript
await client.emails.resend('msg_abc123…')
Terminal
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:

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

Cancel a scheduled email:

Suppressions and category unsubscribes are checked again when a scheduled email goes out. If a recipient was suppressed or opted out of the email's category since you scheduled it, the email isn't sent: its status becomes suppressed, with the reason in bounce_reason, and you get an email.suppressed webhook.

SDK:

CLI:

Scheduled a whole batch? Cancel every email in it that hasn't gone out yet in one call with POST /batches/{id}/cancel.

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.

JSON
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Tomorrow",
  "html": "<p>See you tomorrow.</p>",
  "scheduled_at": "2026-08-01T12:00:00.000Z"
}
HTTP
PATCH /emails/msg_abc123…
JSON
{ "scheduled_at": "2026-08-01T13:00:00.000Z" }
JSON
{ "cancel": true }
TypeScript
await client.emails.update('msg_abc123…', { scheduledAt: '2026-08-01T13:00:00.000Z' })
await client.emails.cancel('msg_abc123…')
Terminal
groundmail emails cancel --id msg_abc123…

Batch send

POST/emails/batch

Send up to 100 emails in one request:

The response is index-aligned, with a batch_id shared by every email the call accepted:

Each of those emails also carries the id as batch_id in GET /emails/{id} and GET /emails. Use it to check on or cancel the batch.

Each item is stored and handed to the mail server in the background, like a single send, so a batch answers quickly: a mail server refusal arrives as email.failed rather than in the item. Each item can name its own tenant. Per-email validation failures are returned in that item’s error. An item whose email went out with some recipients held back by Groundmail validation carries held_back; one with every recipient held back has a validation_error with details.held_back. Attachments are rejected for batch sends in v1.

Send limits are checked for each email in order. If a batch is bigger than what is left of today’s limit, the emails that fit are sent and the rest come back with an error in their item: plan_limit for the Free plan’s 100 a day, daily_ramp_limit for a new account’s ramp-up limit.

Each email in a batch counts toward the account's request rate, as that many POST /emails would. A batch that doesn't fit right now is refused whole with 429 rate_limited and a Retry-After; nothing in it is sent. A batch with more emails than the per-minute rate is refused the same way without Retry-After: split it.

An Idempotency-Key header covers the whole batch, with the same rules as single sends. If no email in the batch was accepted or stored, the key is released so a corrected retry can use it.

SDK:

JSON
{
  "emails": [
    {
      "from": "you@yourdomain.com",
      "to": "user@example.com",
      "subject": "Hello",
      "html": "<p>Hi</p>"
    }
  ]
}
JSON
{
  "batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
  "data": [
    { "index": 0, "id": "msg_abc123…", "status": "queued" }
  ]
}
TypeScript
const result = await client.emails.batch([{ from, to, subject, html }], { idempotencyKey: 'digest-2026-11-02' })
result.batch_id // 'batch_3f9a…'

Batches

A batch is the emails one POST /emails/batch call accepted. Schedule one by giving each email a scheduled_at, then check on it or call it off with its batch_id. A tenant-scoped key sees and cancels only its tenant's emails in a batch.

Get a batch

GET /batches/{id} (scope emails:read)

counts has a key for each status with at least one email. For the emails themselves, use GET /emails/{id} with the ids from the batch response.

JSON
{
  "batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
  "created_at": "2026-11-03T09:00:00.000Z",
  "total": 100,
  "counts": { "scheduled": 98, "sent": 2 }
}

Cancel a batch

POST /batches/{id}/cancel (scope emails:send)

Cancels every email in the batch that is still scheduled, the same way cancelling one does: its status becomes cancelled and cancelled_at is set. Emails already queued, sent or finished are left alone.

It's safe to repeat: a second call cancels nothing more and counts the earlier ones in already_cancelled. Both endpoints return 404 not_found for a batch id that isn't on your account, and once every email in the batch is past your plan's log retention.

SDK:

CLI:

MCP: get_batch and cancel_batch.

JSON
{
  "batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
  "cancelled": 98,
  "already_cancelled": 0,
  "not_cancellable": 2
}
TypeScript
const { batch_id } = await client.emails.batch(emails) // each with scheduledAt
await client.batches.get(batch_id)
await client.batches.cancel(batch_id)
Terminal
groundmail batches get batch_3f9a…
groundmail batches cancel batch_3f9a…

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. test=true lists only test emails, test=false only live ones. tenant=cust_8412 lists one tenant's emails; a key limited to one tenant only ever sees its tenant's. stream=transactional|product|newsletter lists one mail stream's emails.

Responses include rate-limit headers for the monthly quota: ratelimit-limit, ratelimit-remaining, ratelimit-reset. When a daily limit applies (Free's 100 a day, or a new account's ramp-up limit for the email's stream, counted in recipients), they also include ratelimit-daily-limit, ratelimit-daily-remaining and ratelimit-daily-reset.

200

Status values: queued, scheduled, sent, delivered, delayed, opened, clicked, bounced, complained, failed, suppressed, cancelled.

test is true for an email that never reached the mail server: sent with a test key or only to simulator addresses. See Testing.

stream is the mail stream the email went out on, from its category: transactional, product or newsletter. Each stream sends from its own IPs.

detected_category is what Groundmail decided the email is from its content: transactional or product. It's null while the email is being checked, when its template's category wasn't settled yet when it was sent (a new template, or one just published), and for email Groundmail doesn't check: newsletter sends, test sends, agent mailboxes and forwarded mail. An email's category is set once and doesn't change later. stream is what the email went out on. See Detected category.

An email sent for a tenant also carries "tenant": "cust_8412" (the tenant's external_id). Account-level emails have no tenant field.

bounce_type says why an email bounced, and is null until it does:

bounce_type Meaning Recipient suppressed?
hard The address cannot receive mail: unknown user, disabled mailbox, or a domain with no mail server. Yes
block The receiving server refused the message because of the sending IP's or domain's reputation or policy, for example a blocklist listing or a mailbox provider's spam policy. The address itself is fine. No. Block bounces also do not count toward your bounce rate, and you can send to the address again later.

bounce_reason carries the receiving server's reply when there is one (for example 550 5.1.1 user unknown).

An email the receiving server refuses for its size (for example 552 5.3.4 Message size exceeds fixed limit) is not a bounce: it gets status failed, an email.failed webhook, bounce_type: null and the reply in bounce_reason. The recipient is not suppressed, so a smaller email (link to large files instead of attaching them) reaches them. See attachment limits.

opened_at and clicked_at record the first open and the first tracked-link click. They stay null unless open or click tracking is on for the sending domain (see Domains).

JSON
{
  "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,
      "bounce_type": null,
      "delivery": {
        "receiving_server": "mx.example.com",
        "response": "250 2.0.0 Ok: queued as 4F2B1C",
        "tls": true,
        "deferred_response": null,
        "deferred_at": null
      },
      "held_back": [],
      "test": false,
      "stream": "transactional",
      "detected_category": "transactional",
      "tags": [],
      "batch_id": null,
      "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,
      "opened_at": null,
      "clicked_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

SDK

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

Error format

All errors return:

Status When
400 Invalid JSON, missing fields, invalid from (not exactly one address: a list, a group, a line break, or an unquoted name with special characters), invalid to, cc or bcc entry (not exactly one address: a list in one string, a group, a line break, or angle brackets in the name)
401 Missing/invalid Bearer token or API key
403 from domain not verified, sandbox/verified-domain sender used for recipients outside the account email, or send to other recipients without Free production unlocked (payment method on file). With tenants: tenants_not_enabled (your plan has no tenants), a paused or transactional_only tenant, or from on another tenant's domain (domain_not_allowed). newsletter_not_enabled for category: "newsletter" on an account not approved for newsletters
404 tenant names no tenant of this account
409 Idempotency key conflict
422 A recipient is suppressed or opted out of the category, Groundmail validation held back every recipient, or sender names a sender your team doesn't have
413 The request is over 20MB, Base64-encoded attachments included (attachment limits)
429 Send limit reached: the Free plan limit (plan_limit), or a new account's daily ramp-up limit (daily_ramp_limit, details), or the tenant's own ramp or daily limit (daily_ramp_limit with details.tenant, details)
502 Mail server error on an email handed over during the request (one with attachments). A queued send gets email.failed instead
503 Mail delivery temporarily unavailable: nothing was sent, retry
JSON
{
  "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
  • Maximum 20MB for the whole request (or SMTP message), Base64-encoded attachments included. Base64 makes files about a third larger, so that's about 14MB of files. A larger request gets 413 with code validation_error, and the SMTP relay refuses a larger message with 552 5.3.4. Link to large files instead of attaching them: many company mail servers refuse messages over 10MB anyway.
  • Blocked filename extensions: .exe, .bat, .cmd, .com, .scr, .js, .vbs, .dll

Examples

curl

Terminal
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

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

TypeScript
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>',
})

CLI

Add --watch to wait until the recipient's mail server accepts or refuses it, with its reply and the time it took: see Watch an email land.

Signs in with groundmail login, or uses GROUNDMAIL_API_KEY or --api-key.

Terminal
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

OpenAPI

Machine-readable spec: OpenAPI spec

Was this page helpful?