API explorer
Browse the Groundmail API (0.17.0) contract and send live requests with your gm_ key.
/emailsemails:sendSend 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/emailsSend 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
Invalid request
Invalid request (including category set to newsletter)
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.
tenant that does not exist in this accountIdempotency key conflict
Idempotency key conflict (payload mismatch or concurrent request)
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.
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).
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.
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.
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.