Connect n8n & external tools

Outbound HTTP workflow#

Use n8n's HTTP Request node or an equivalent backend HTTP client. No custom Mailat plugin is required.

1. Create a Mailat key with only the scopes your workflow needs.
2. Store Authorization: Bearer <key> in the tool's credential store, not in exported workflow JSON.
3. Set the URL to your instance origin plus the documented /api/v1/... path.
4. Configure the method, content type and JSON body from the operation's reference.
5. Generate and persist a stable idempotency key from your workflow's business job ID before a send.
6. Inspect HTTP and body results; apply bounded retry/backoff and respect Retry-After.

For a welcome-email workflow, call POST /emails with email:send. Retrying the same execution must reuse its key and body, while a genuinely new job gets a new key. Avoid a current timestamp as your only deduplication strategy.

Incoming-email workflow#

Use a public HTTPS webhook receiver that preserves the raw request bytes. Verify the Mailat signature before trusting parsed fields. If your workflow service cannot expose the unmodified body, put a small verified receiver in front of it.

Persist the event ID in durable storage, fetch the message with email:read, perform your action, and record completion. When organizing mail, add email:manage and use the explicit received-mail mutations. Do not create reply loops by replying to your own events or all automated messages.

Use a periodic change-feed catch-up job alongside notifications. Store its last completed cursor outside the execution's temporary memory. An expired cursor requires a fresh snapshot.

Other resources#

The reference includes contacts, lists, templates, domains and identities. Each operation shows whether API keys can call it and the exact scope. Use owned IDs from list/create results, not guessed numeric identifiers. Template variables and contact fields are untrusted content; escape them appropriately in your own rendering.

The repository includes SDK source for JavaScript, Python and Go. Inspect the pinned release and examples before choosing an SDK; these docs do not assume packages are published to a registry. Direct HTTP is sufficient for every supported API-key operation.

Operational checklist#

• Keep Mailat origin, workflow credentials and webhook secret as separate settings.
• Log message/event IDs and HTTP statuses, not tokens or message bodies by default.
• Handle duplicate events, partial batch results, expired cursors and provider outages.
• Review dead letters and unexpected unknown, bounce or complaint events.
• Pin your integration to a Mailat release and compare its embedded OpenAPI when upgrading.