Build with the DynaMail API

Quickstart

1. 1

   Create API keys

   In Dashboard → API Keys, create a Full access key for the widget creation step. For recurring pushes, create a separate Automation key and keep each key in your credential store.

2. 2

   Find your account ID

   Call GET /me. The returned data.id is YOUR_ACCOUNT_ID in the next request.

   Request

   curl https://api.dynamail.io/me \
     -H "X-API-Key: dm_sk_your_key_here"

   200 response

   {
     "success": true,
     "data": { "id": "YOUR_ACCOUNT_ID" }
   }

3. 3

   Create a Stat Counter

   POST /widgets requires widgets:write, which is included in the Full access preset.

   Request

   curl --request POST 'https://api.dynamail.io/widgets' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: dm_sk_your_key_here' \
     --data '{"name":"Signups","type":"stat_counter","userId":"YOUR_ACCOUNT_ID","config":{"value":1250,"label":"Signups this week"}}'

   201 response (trimmed)

   {
     "success": true,
     "data": {
       "id": "WIDGET_ID",
       "userId": "YOUR_ACCOUNT_ID",
       "type": "stat_counter",
       "name": "Signups",
       "config": {
         "value": 1250,
         "label": "Signups this week",
         "dslLayout": "…",
         "tokens": "…"
       },
       "createdAt": "2026-09-12T12:34:56.789Z",
       "updatedAt": "2026-09-12T12:34:56.789Z"
     }
   }

   The API stamped the default layout and tokens, so the minimal configuration is ready to render. Save data.id as WIDGET_ID.

4. 4

   Embed the image

   API calls use api.dynamail.io; delivered images use img.dynamail.io. The stamped Stat Counter is 340×184.

   HTML embed

   Copy

   <img src="https://img.dynamail.io/widgets/WIDGET_ID/render.png" width="340" height="184" alt="Signups this week">

5. 5

   Push a live value

   Use the Automation key, which includes live-value:write. Increase sourceVersion with each newer upstream event.

   Request

   curl --request PUT 'https://api.dynamail.io/widgets/WIDGET_ID/live-value' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: dm_sk_your_key_here' \
     --data '{"value":1250,"sourceVersion":1}'

   200 receipt

   {
     "success": true,
     "data": {
       "widgetId": "WIDGET_ID",
       "revision": 1,
       "active": true,
       "value": 1250,
       "sourceVersion": 1,
       "updatedAt": "2026-09-12T12:34:56.789Z",
       "applied": true,
       "reason": "applied"
     }
   }

   Check data.applied and data.reason; a successful HTTP response can report a stale or unchanged event.

6. 6

   Optional: personalize by recipient

   Add the same recipient identifier to the update and the image URL.

   Recipient request

   curl --request PUT 'https://api.dynamail.io/widgets/WIDGET_ID/live-value' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: dm_sk_your_key_here' \
     --data '{"value":1250,"sourceVersion":1,"recipient":"person@example.com"}'

   Recipient HTML embed

   Copy

   <img src="https://img.dynamail.io/widgets/WIDGET_ID/render.png?recipient=person%40example.com" width="340" height="184" alt="Signups this week">

   For many recipients, PUT /widgets/WIDGET_ID/live-value/bulk accepts 1–500 unique recipient entries in one request.

Endpoint reference

Schema names identify each operation's request and response shapes in the downloadable OpenAPI document. An empty scopes field means the endpoint is public or only requires a valid key, as described in its summary.

Errors and rate limits

Hourly account quota

Authenticated widget calls share one hourly allowance across all of an owner’s keys and client IPs. Unresolved key attempts also have a 300-per-minute, per-IP protection. For both 429 quota exhaustion and 503 quota-storage outages, honor Retry-Afterand retry unchanged input; a 503 currently reports a five-second delay. For most widget types, PATCH /widgets/:id replaces the complete stored config.

Frequently asked questions