API explorer

Browse the Groundmail API (0.17.0) contract and send live requests with your gm_ key.

POST/emailsemails:send

Send a transactional email

Checks the send (domain, limits, suppressions, Groundmail validation), stores the email and answers. status can be queued: the email is accepted and handed to the mail server in the background, so the response doesn't wait for that hand-off. The outcome then arrives on GET /emails/{id} and through webhooks: email.delivered when it lands, or status: failed with bounce_reason and an email.failed webhook if the mail server refuses it. A send answered queued never gets an upstream_error; temporary mail server problems are retried for you for about 15 minutes. Emails with attachments are handed over during the request, so a mail server problem with one is a 502, 503 or 504 upstream_error here.

https://api.groundmail.dev/emails
Response

Send the request to see the response here.

Then follow it

Follow it with GET /emails/{id} or webhooks: email.delivered when it lands, email.failed (with bounce_reason) if it cannot be sent.

Documented responses

200Email accepted for delivery
400
Invalid request

Invalid request (including category set to newsletter)

401Missing or invalid API key
403
From domain not verified, sandbox/verified-domain sender used for non-account recipients, send to other recipients without a paid plan, or sending paused for the workspace

From domain not verified, sandbox/verified-domain sender used for non-account recipients, send to other recipients without a paid plan, or sending paused for the workspace. stream_paused when the account's product or newsletter email is paused after high bounce or complaint rates (details.stream). newsletter_not_enabled when the send uses category: newsletter and the account is not approved for newsletter sending. For tenants: tenants_not_enabled when the send names a tenant on a plan without tenants; forbidden when the tenant is paused, is transactional_only and the email is product or newsletter email, or a key limited to one tenant names another; domain_not_allowed when from is on another tenant's domain.

404The send names a tenant that does not exist in this account
409
Idempotency key conflict

Idempotency key conflict (payload mismatch or concurrent request)

413
The request is over 20MB, Base64-encoded attachments included

The request is over 20MB, Base64-encoded attachments included (validation_error), or the built email is too large for the mail server (upstream_error). Link to large files instead of attaching them.

422
Recipient is suppressed or opted out of the email category, or Groundmail validation held back every to recipient

Recipient is suppressed or opted out of the email category, or Groundmail validation held back every to recipient (details.held_back). When only some recipients are held back, the email goes to the rest and the 200 response lists them in held_back. Also returned when sender names a sender this workspace doesn't have (validation_error).

429
Send limit reached

Send limit reached. plan_limit: the Free plan's daily or monthly limit (paid plans meter overage instead). daily_ramp_limit: this send would go over a new account's daily ramp-up limit for its stream, or over its tenant's own ramp or daily_limit (then details.tenant is set); it has no upgrade_url and details.resets_at says when to send the rest.

502
Mail server error

Mail server error (upstream_error) on an email handed over during the request, such as one with attachments. A send answered queued reports a mail server refusal as status: failed and email.failed instead.

503
Mail delivery is unavailable

Mail delivery is unavailable (not_configured), or the mail server could not take an email handed over during the request (upstream_error). Nothing was sent: retry.