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:

FieldValue
NameAuthorization
ValueBearer os_live_…

Send an email (HTTP Request node)

SettingValue
MethodPOST
URLhttps://<your OneSend host>/v1/emails
AuthenticationGeneric Credential Type → Header Auth → the credential above
Send HeadersOn. Name Idempotency-Key, value {{ $execution.id }}-{{ $itemIndex }}
Send BodyOn. 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

PurposeRequest
Check an address before adding it to a listPOST /v1/tools/address with { "email": "{{ $json.email }}" }
Add or update a contactPOST /v1/contacts with { "email": …, "firstName": …, "listIds": ["lst_…"] }
Get an email's delivery statusGET /v1/emails/{{ $json.id }}
Receive delivery eventsA 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):

SettingValue
HostYour OneSend host
Port2587
SSL/TLSOff; STARTTLS is used when the server has TLS configured
UserAny value, for example onesend
PasswordA 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.