Getting started
Introduction
REST API under /v1. Integrators authenticate with an opaque API token. Identities and templates are configured in the admin dashboard — tokens cannot list them.
Base URL: https://gateway.tag.mw/v1
Getting started
Authentication
Authorization: Bearer eg_xxxxxxxxxxxxxxxxxxxxxxxx| Scope | Behavior |
|---|---|
ALL_IDENTITIES | Send as any verified identity (pass from). |
SINGLE_IDENTITY | Bound identity only. You may omit from. |
MULTI_IDENTITY | Only listed identities; from required and must be in scope. |
What your token can call
POST /v1/messages, POST /v1/messages/extended, GET /v1/messages* (your sends), and /v1/webhooks* (your endpoints). No identity or template listing.Getting started
Rate limiting
Global limit default 300/minute; tokens may set rate_limit_per_minute. Over limit → 429 RATE_LIMITED.
Conventions
Lists & pagination
{
"data": [ /* … */ ],
"pagination": {
"total": 0,
"page": 1,
"page_size": 50,
"has_more": false
}
}Conventions
Errors
{
"code": "VALIDATION_ERROR",
"message": "subject is required",
"request_id": "a1b2c3d4"
}Conventions
Idempotency
Pass Idempotency-Key on send. Same body → original response; different body → 409 IDEMPOTENCY_CONFLICT.
Endpoints
Health
/v1/healthPublic/v1/readyPublicEndpoints
Messages
/v1/messagesAPI tokenUse from (sender email) and optional template (unique name). With SINGLE_IDENTITY tokens, omit from.
curl -X POST https://gateway.tag.mw/v1/messages \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": "no-reply@example.com",
"to": ["user@example.com"],
"subject": "Hello",
"text": "Plain body"
}'Extended / bulk template send
/v1/messages/extendedAPI token{
"from": "billing@example.com",
"template": "invoice-ready",
"messages": [
{ "email": "a@example.com", "variables": { "name": "Alice" } }
]
}No numeric IDs required
List & detail
/v1/messagesAPI token/v1/messages/{id}API tokenTokens only see messages they created.
Endpoints
Webhooks
/v1/webhooksAPI token/v1/webhooksAPI token/v1/webhooks/{id}/rotate-secretAPI token/v1/webhooks/{id}API tokenSigning header X-Signature: sha256=…. Secret returned once; stored encrypted at rest.