Docs / Developers and AI
n8n
Send email from n8n workflows through OneSend with the HTTP Request node, or through the Send Email node over SMTP.
Credentials
Create an API key under Developers → API keys (Sending only is enough to send). In n8n, create a credential of type Header Auth:
| Field | Value |
|---|---|
| Name | Authorization |
| Value | Bearer os_live_… |
Send an email (HTTP Request node)
| Setting | Value |
|---|---|
| Method | POST |
| URL | https://<your OneSend host>/v1/emails |
| Authentication | Generic Credential Type → Header Auth → the credential above |
| Send Headers | On. Name Idempotency-Key, value {{ $execution.id }}-{{ $itemIndex }} |
| Send Body | On. Body Content Type: JSON, Specify Body: Using JSON |
Body:
{
"from": "Acme <hello@acme.dev>",
"to": "{{ $json.email }}",
"subject": "Your order {{ $json.orderId }} has shipped",
"template": "order-shipped",
"variables": { "name": "{{ $json.name }}", "tracking_url": "{{ $json.trackingUrl }}" },
"tags": ["n8n", "shipping"]
}
The response is { "id": "msg_…", "status": "queued" } with HTTP 202. The Idempotency-Key makes a retried execution return the same email instead of sending a second one.
For several recipients at once, POST /v1/emails/batch takes { "emails": [ … ] } with up to 100 items.
Errors
OneSend answers errors with a 4xx or 5xx status and { "error": { "code", "message" } }. In the node settings, turn on Retry On Fail for 429 and 5xx responses, and use On Error → Continue (using error output) to route 4xx errors (for example validation_failed or domain_not_allowed) to a branch that alerts you instead of retrying.
Other useful requests
| Purpose | Request |
|---|---|
| Check an address before adding it to a list | POST /v1/tools/address with { "email": "{{ $json.email }}" } |
| Add or update a contact | POST /v1/contacts with { "email": …, "firstName": …, "listIds": ["lst_…"] } |
| Get an email's delivery status | GET /v1/emails/{{ $json.id }} |
| Receive delivery events | A Webhook trigger node, registered under Developers → Webhooks (see Webhooks) |
Send Email node (SMTP)
The Send Email node can use OneSend's SMTP ingress instead (see SMTP):
| Setting | Value |
|---|---|
| Host | Your OneSend host |
| Port | 2587 |
| SSL/TLS | Off; STARTTLS is used when the server has TLS configured |
| User | Any value, for example onesend |
| Password | A OneSend API key |
Add the header X-OneSend-Tags: n8n to tag the messages. Use the HTTP Request node when you need templates, variables or idempotency.