Send email
/emailsSend 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>"
}'import { Groundmail } from 'groundmail'
const groundmail = new Groundmail(process.env.GROUNDMAIL_API_KEY!)
const { id, status } = await groundmail.emails.send({
from: 'Acme <hello@mail.acme.io>',
to: 'maya@northwind.io',
subject: 'Reset your password',
html: '<p>Your code is 482913</p>',
idempotencyKey: 'reset-8841',
})import os
from groundmail import Groundmail
groundmail = Groundmail(os.environ["GROUNDMAIL_API_KEY"])
result = groundmail.emails.send(
from_="Acme <hello@mail.acme.io>",
to="maya@northwind.io",
subject="Reset your password",
html="<p>Your code is 482913</p>",
)client, err := groundmail.New(os.Getenv("GROUNDMAIL_API_KEY"))
if err != nil {
log.Fatal(err)
}
result, err := client.Emails.Send(map[string]any{
"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"
}{
"error": {
"message": "One or more recipients are suppressed",
"code": "validation_error",
"hint": "…",
"docs_url": "https://docs.groundmail.dev/errors#validation_error",
"details": { "suppressed": ["maya@northwind.io"] }
}
}{
"error": {
"code": "plan_limit",
"message": "…",
"hint": "…",
"docs_url": "https://docs.groundmail.dev/errors#plan_limit",
"upgrade_url": "/settings/billing"
}
}Authentication
API keys are created in the dashboard (API Keys). Keys start with gm_.
Authorization: Bearer gm_…Request body
fromstring or { email, name? }requiredyou@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"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[]requiredada@example.com, Ada <ada@example.com> or "Lovelace, Ada" <ada@example.com>. Pass several as an array: each entry is exactly one address.subjectstringrequiredhtmlstringNo*htmlBody / html_body aliases accepted)textstringNo*textBody, text_body, and plain_body aliases accepted)reply_tostring or string[]optionalreplyTo alias accepted)ccstring or string[]optionaltobccstring or string[]optionaltotags{ name, value }[] or objectoptionalheadersobjectoptionalattachmentsarrayoptionalfilename, contentType, content, and contentId are also accepted.scheduled_atstringoptionalscheduledAt alias accepted)unsubscribebooleanoptionalvalidationobjectoptional{ "block_bot_signups": true } holds back addresses that look like bot sign-ups (details). Off by default.categorystringoptionaltransactional and product are accepted and ignored. newsletter still sends an opt-in newsletter, for approved accounts: see Newsletter category.tenantstringoptionalexternal_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:
from(andreply_to) on the request.senderon the request: a saved sender's name, address and reply-to.- The template's sender, when you send a template that has one.
- 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.
{
"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-UnsubscribeandList-Unsubscribe-Postheaders (one-click unsubscribe) - Replaces
{{unsubscribe_url}}insubject,html, andtextwith a signed confirmation link - Binds the link to the first
toaddress 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-Unsubscribeand one-click unsubscribe (List-Unsubscribe-Post), and{{unsubscribe_url}}is filled in;unsubscribe: falseis a400validation_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.
{
"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"
}
}{
"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_…"
}
}
}{
"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:
{
"from": "you@yourdomain.com",
"to": "user@example.com",
"subject": "Hello from Groundmail",
"html": "<p>It works.</p>"
}{
"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.
{
"from": "noreply@mail.groundmail.dev",
"to": "owner@example.com",
"subject": "Sandbox check",
"html": "<p>Sandbox works.</p>"
}{
"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.deliveredwhen the recipient's mail server accepts it;status: "failed"with abounce_reason, and anemail.failedwebhook, if the mail server refuses it. A refusal like that used to come back as anupstream_erroron the send call; for aqueuedsend 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.
{
"id": "msg_abc123…",
"status": "queued"
}{
"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.
{
"id": "msg_abc123…",
"status": "queued",
"held_back": [{ "email": "ada@no-mail.example", "reason": "no_mail_server" }]
}{
"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.
Idempotency-Key: order-123await client.emails.send({ …, idempotencyKey: 'order-123' })
await client.emails.batch([…], { idempotencyKey: 'digest-2026-11-02' })Retrieve email
/emails/{id}Returns one send by public id (msg_…).
Emails older than your plan's data retention window return the normal 404 not_found.
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.
{
"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
/emails/{id}/resendCreates 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:
await client.emails.resend('msg_abc123…')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.
{
"from": "you@yourdomain.com",
"to": "user@example.com",
"subject": "Tomorrow",
"html": "<p>See you tomorrow.</p>",
"scheduled_at": "2026-08-01T12:00:00.000Z"
}PATCH /emails/msg_abc123…{ "scheduled_at": "2026-08-01T13:00:00.000Z" }{ "cancel": true }await client.emails.update('msg_abc123…', { scheduledAt: '2026-08-01T13:00:00.000Z' })
await client.emails.cancel('msg_abc123…')groundmail emails cancel --id msg_abc123…Batch send
/emails/batchSend 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:
{
"emails": [
{
"from": "you@yourdomain.com",
"to": "user@example.com",
"subject": "Hello",
"html": "<p>Hi</p>"
}
]
}{
"batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
"data": [
{ "index": 0, "id": "msg_abc123…", "status": "queued" }
]
}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.
{
"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.
{
"batch_id": "batch_3f9a1c2b7d4e5f60718293a4",
"cancelled": 98,
"already_cancelled": 0,
"not_cancellable": 2
}const { batch_id } = await client.emails.batch(emails) // each with scheduledAt
await client.batches.get(batch_id)
await client.batches.cancel(batch_id)groundmail batches get batch_3f9a…
groundmail batches cancel batch_3f9a…List emails
/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).
{
"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
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 |
{
"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
413with codevalidation_error, and the SMTP relay refuses a larger message with552 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
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).
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.
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.000ZOpenAPI
Machine-readable spec: OpenAPI spec