Core
Triggered emails
Send a single transactional email — verification codes, receipts, password resets, invites — by referencing a trigger you set up once in the dashboard. Your code supplies the recipient and variables; the template lives in Meisa.
How it works
In the dashboard you create a trigger: a template, a sender, and a stable trigger_key (e.g. verification_code). Your backend then fires that trigger by key. This keeps email content and design out of your codebase and in the hands of the people who own it.
Send a triggered email
POST
/emails/trigger/scope: emails:trigger| Field | Type | Description |
|---|---|---|
trigger_keyrequired | string | The key of a trigger configured in Meisa. Must exist and be active. |
to_emailrequired | string | The single recipient. |
variables | object | Values merged into the template, e.g. { name, code } for {{name}} / {{code}}. |
recipient | object | Contact fields (e.g. first_name) used to auto-create or enrich the contact if it doesn't exist yet. |
idempotency_key | string | Dedupes identical sends within one hour. Use it to make retries safe. |
trigger an email
curl -X POST "https://api.meisa.io/api/v1/emails/trigger/" \
-H "X-API-Key: meisa_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"trigger_key": "verification_code",
"to_email": "[email protected]",
"variables": { "name": "Sarah", "code": "294817" },
"recipient": { "first_name": "Sarah" },
"idempotency_key": "verify_usr_12345_294817"
}'Responses
The outcome depends on the trigger's configuration:
| Field | Type | Description |
|---|---|---|
200 sent | — | Delivered. Returns email_send_id, contact_id, and contact_created. |
202 scheduled | — | The trigger has a configured delay, so the send was scheduled. |
200 skipped | — | The trigger's conditions weren't met (reason: conditions_not_met). |
422 | — | Recipient is unsubscribed, or no sender is configured for the trigger. |
429 | — | Rate limited by a guardrail or your key's limits. |
400 | — | Unknown/inactive trigger_key, or an invalid to_email. |
Common trigger keys
You define your own keys, but typical transactional triggers look like verification_code, payment_failure, and various invite emails. One call sends to one recipient.
Use idempotency keys for retry safety
Network blips happen. Pass a deterministic idempotency_key (e.g. verify_{user_id}_{code}) so a retried request within the hour won't send a duplicate email.