groundmail-dev Events API
Custom events that trigger transactional automations
Custom events that trigger transactional automations
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/groundmail-dev:groundmail-dev-events-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Groundmail Events API
version: 0.16.0
description: 'Transactional email API for developers.
Auth: `Authorization: Bearer gm_…` with an API key, or `Bearer gm_oat_…` with an OAuth
access token from the device flow (`groundmail login`). Dashboard session cookies work
for integrations.
Azure managed identity (keyless): an Azure workload can send a Microsoft Entra access
token (a JWT) as the Bearer credential instead of a key. Register the identity''s tenant
ID, object ID and token audience in the dashboard (API keys → Azure managed identity);
it then has the same access options as an API key (scopes, domain limit, tenant).
App-only tokens only. Any authentication failure is the same 401 `unauthorized`.
See https://docs.groundmail.dev/authentication/azure-managed-identity.
Test mode: a test key (`gm_test_…`, `POST /api-keys` with `test: true`) behaves
like a live key, but its sends are never delivered: they are stored with
`test: true`, get simulated events and webhooks (`data.test: true`), and do not
count toward plan limits, the sending ramp, stats or billing. Simulator
addresses (`delivered@`, `bounce@`, `block@`, `complaint@`, `suppressed@`,
`delayed@simulator.groundmail.dev`, plus addressing allowed) produce one outcome
each with any key. See https://docs.groundmail.dev/testing.
Tenants: a platform that sends email for its own customers creates one tenant per
customer (`/tenants`), each with its own domains, suppression list, stats, sending
ramp and pause switch. Name the tenant with `tenant` on sends, domains and
suppressions, or send from a domain the tenant owns. API keys and webhook
endpoints can be limited to tenants. Included on pay as you go and the Dedicated plan;
elsewhere a request that names a tenant gets 403 `tenants_not_enabled`. See
https://docs.groundmail.dev/tenants.
Data retention: sent emails (content and events) and received emails are kept for
your plan''s window, then deleted: 7 days on Free, 30 on Pro, 90 on Scale, up to 365
on Dedicated. Past it, `GET /emails/{id}` and `GET /received-emails/{id}` return
404 `not_found` and lists no longer include them. Aggregate stats
(`GET /deliverability`) are kept. Store webhook events to keep history longer. See
https://docs.groundmail.dev/emails#data-retention.
Scopes: every credential carries scopes (`full`, `emails:send`, `emails:read`,
`domains:read`, `domains:write`, `webhooks:write`, `templates:write`,
`suppressions:write`, `account:read`). Each operation lists the scope it needs under
`x-required-scope` (space-separated: all of them; `a | b`: either); a credential
without it gets 403 `insufficient_scope` with `required_scope`. `full` grants everything; `domains:write` includes `domains:read`.
Legacy `sending` API keys have `emails:send` + `emails:read`.
Production base URL: https://api.groundmail.dev'
servers:
- url: https://api.groundmail.dev
description: Production
tags:
- name: Events
description: Custom events that trigger transactional automations
paths:
/events:
post:
operationId: triggerEvent
x-required-scope: emails:send
summary: Ingest a custom event for automations
tags:
- Events
security:
- bearerAuth: []
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 256
description: Optional idempotency key for replay-safe retries.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerEventRequest'
examples:
userCreated:
value:
name: user.created
user_id: user_123
email: user@example.com
data:
name: Ada Lovelace
responses:
'202':
description: Event accepted for automation processing
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerEventResponse'
'400':
description: Invalid event payload
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key / session
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Idempotency conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
TriggerEventResponse:
type: object
required:
- event
- matched_automations
- resumed_runs
- cancelled_runs
properties:
event:
$ref: '#/components/schemas/EventRecord'
matched_automations:
type: integer
resumed_runs:
type: integer
cancelled_runs:
type: integer
description: Active runs cancelled because this event matched `trigger.cancel_on_events`
skipped_enrollments:
type: integer
description: Automations whose trigger matched but did not start a run, because of `trigger.once_per_contact` or `trigger.cooldown_days`
enrollment_skips:
type: array
description: Present when `skipped_enrollments` is above zero. One entry per automation that declined to enrol this recipient again.
items:
type: object
required:
- automation_id
- reason
- prior_run_id
- prior_run_at
properties:
automation_id:
type: string
reason:
type: string
enum:
- once_per_contact
- cooldown
prior_run_id:
type: string
prior_run_at:
type: string
format: date-time
ErrorResponse:
type: object
required:
- error
properties:
error:
type: object
required:
- message
properties:
message:
type: string
description: What went wrong, in plain English. Wording can change; branch on `code`.
code:
$ref: '#/components/schemas/ErrorCode'
hint:
type: string
description: 'How to fix the error. Specific to the failure when known (for example a sandbox recipient), otherwise the default for `code`.
'
docs_url:
type: string
format: uri
description: Link to this code on the errors page, `https://docs.groundmail.dev/errors#<code>`.
example: https://docs.groundmail.dev/errors#validation_error
upgrade_url:
type: string
description: 'Dashboard path to upgrade when code is plan_limit or domain_limit. Absent for `daily_ramp_limit`, which upgrading does not lift.
'
required_scope:
type: string
description: 'With `insufficient_scope`: the scope (or space-separated scopes) the operation needs. Also sent as `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`.
'
details:
description: 'Optional structured details. For send blocks this may include `suppressed` (global suppression list) or `category_unsubscribed` plus `category` and `email_id` (category opt-out). A `daily_ramp_limit` carries `stream` (`transactional` or `product`), `daily_limit` (today''s recipient limit for that stream), `used_today`, `recipients` (in this send), `ramp_stage` and `resets_at` (next 00:00 UTC, ISO 8601), plus `tenant` when the tenant''s own limit refused the send.
'
EventRecord:
type: object
required:
- id
- name
- user_id
- email
- data
- source
- created_at
properties:
id:
type: string
name:
type: string
user_id:
type: string
nullable: true
email:
type: string
nullable: true
format: email
data:
type: object
additionalProperties: true
source:
type: string
enum:
- api
- dashboard
created_at:
type: string
format: date-time
ErrorCode:
type: string
description: 'Stable, machine-readable error code. Each code is documented at
`https://docs.groundmail.dev/errors#<code>`. New codes may be added;
existing codes keep their meaning.
- `validation_error` (400, 422): the request failed validation, or every recipient is suppressed or opted out (422). Fix the field named in `message`/`details`.
- `unauthorized` (401): missing, malformed or revoked API key. Send `Authorization: Bearer gm_…`.
- `forbidden` (403): the key is valid but the action is not allowed (unverified `from` domain, sandbox send to someone other than the account email, no payment method on file, sending restricted).
- `insufficient_scope` (403): the API key''s scope does not cover this endpoint.
- `domain_not_allowed` (403): the API key is limited to other sending domains than the one in `from`, or `from` is on another tenant''s domain.
- `tenants_not_enabled` (403): the request names a tenant, but tenants are not enabled for this account. They are included on pay as you go and the Dedicated plan.
- `newsletter_not_enabled` (403): the send uses `category: "newsletter"`, but newsletter sending isn''t enabled on this account. Newsletter email is accepted only for approved accounts.
- `not_found` (404): no resource with that id for this team.
- `conflict` (409): the resource already exists or its state blocks the change.
- `plan_limit` (429): the plan''s monthly or daily sending limit was reached. See `upgrade_url`.
- `daily_ramp_limit` (429): the send would go over a new account''s daily ramp-up limit for its stream, or its tenant''s own ramp or daily limit (`details.tenant`). Upgrading does not lift it; wait for `details.resets_at`.
- `domain_limit` (403): the plan''s domain limit was reached. See `upgrade_url`.
- `idempotency_conflict` (409): the `Idempotency-Key` was reused with a different body, or the first request is still running.
- `rate_limited` (429): too many requests. Wait `Retry-After` seconds.
- `timeout` (408): a long-poll (GET /test-inbox/wait) ended before a matching email arrived. Safe to call again.
- `upstream_error` (502, 503, 504, or a passed-through 4xx): the mail server did not accept the request. 502/503 are safe to retry with the same `Idempotency-Key`; 504 means the outcome is unknown.
- `not_configured` (503): the feature is temporarily unavailable.
- `internal_error` (500): unexpected server error. Retry with backoff.
'
enum:
- validation_error
- unauthorized
- forbidden
- insufficient_scope
- not_found
- conflict
- plan_limit
- daily_ramp_limit
- domain_limit
- idempotency_conflict
- rate_limited
- timeout
- upstream_error
- not_configured
- internal_error
- domain_not_allowed
- tenants_not_enabled
- newsletter_not_enabled
TriggerEventRequest:
type: object
properties:
name:
type: string
description: 'Canonical event name (alias: `type`)'
type:
type: string
description: Alias for name
user_id:
type: string
userId:
type: string
description: Alias for user_id
email:
type: string
format: email
data:
type: object
additionalProperties: true
anyOf:
- required:
- name
- required:
- type
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Groundmail API key (`gm_…`), OAuth access token (`gm_oat_…`), or a Microsoft Entra access token from an Azure managed identity registered in the dashboard (keyless; see https://docs.groundmail.dev/authentication/azure-managed-identity). All carry scopes; see the API description.
'