Use the Atriomail API in n8n with the HTTP Request node

There is no native Atriomail node for n8n. You call the Atriomail REST API with n8n's generic HTTP Request node instead, and the same approach works in any tool that can send HTTPS requests with a custom header.

This page covers the two requests most workflows start with: reading your domains and creating a mailbox. The requests below match the API as of 17 September 2026.

Before you start

• An Atriomail account. Creating one is free and needs no card. Mailboxes are billed from the first one.
• A domain in that account. Each new domain goes through an automated security check before mailboxes can be created on it, and some domains are held for review first.
• An active subscription. Creating your first mailbox in the control panel starts your monthly subscription through Stripe checkout. Do that before you create mailboxes through the API, which are then billed on that same subscription.
• An n8n instance where you can create credentials and edit workflows.

The request basics

Item	Value
Base URL	https://system.atriomail.com/api/v1
Authentication	Your API key in the X-API-KEY request header
Format	JSON request bodies and JSON responses
Recommended header	Accept: application/json
Rate limit	Up to 30 requests per minute

Send the Accept: application/json header on every request. The API's normal answers are JSON either way, and this header makes sure error answers, such as a rate-limit refusal, come back as JSON too, which is easier to handle in a workflow.

Step 1: Create an API key in the control panel

Sign in to the Atriomail control panel, open Settings, then API Keys, and create a new key.

1. Enter a key name you will recognize later, for example n8n.
2. Optionally set an expiration date. Leave it empty for a key that does not expire.
3. Leave the key active and save it.

The panel shows the full key once, right after you save it. Copy it straight away. Atriomail stores the key hashed, so the full key cannot be shown to you again (the API Keys list shows only a masked version, enough to tell keys apart). If you lose it, use Regenerate on the API Keys list: that issues a new key, and the old one stops working.

You can also switch a key off from its edit page. Repeated failed attempts with a wrong key are temporarily locked out.

Step 2: Add a Header Auth credential in n8n

In n8n, create a credential of the Header Auth type, set its name to X-API-KEY, and paste your API key as its value.

The credential's name is the header name, X-API-KEY. Letter case does not matter, but the spelling and hyphens do, so copy it from this page. Give the credential itself a clear label, for example "Atriomail API", so you can pick it from a list later. Every HTTP Request node in the next steps uses this one credential, so the key lives in one place and you only update it there if you regenerate it.

In the HTTP Request node, choose a generic credential type for authentication, pick Header Auth, and select the credential you just made. Menu labels vary a little between n8n versions, so look for those words rather than an exact path.

Step 3: List your domains with a GET request

Add an HTTP Request node that sends GET to https://system.atriomail.com/api/v1/domains using the Header Auth credential from step 2.

Method:          GET
URL:             https://system.atriomail.com/api/v1/domains
Authentication:  Header Auth credential (X-API-KEY)
Send headers:    on
Header:          Accept: application/json

Switch on the node's send-headers option and add a header named Accept with the value application/json. Labels vary a little between n8n versions.

To test the key outside n8n first, the same request with curl looks like this:

curl https://system.atriomail.com/api/v1/domains \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

A trimmed example response:

{
  "data": [
    {
      "id": 42,
      "domain_name": "example.com",
      "active": true,
      "owner_id": 7,
      "provisioning_state": "ready",
      "max_mailboxes": null,
      "storage_quota_mb": null,
      "mailboxes_used": 3,
      "storage_allocated_mb": 46080,
      "storage_used_mb": 1210,
      "mailboxes_count": 3
    }
  ],
  "timestamp": "2026-09-17T09:30:00+00:00"
}

The real response carries a few more fields for each domain (its description, its created and updated dates, and created_by), plus links and meta objects with the pagination details. The example keeps the fields this walkthrough uses.

The fields that matter here

Field	What it tells you
id	The domain's id. You send it as domain_id when you create a mailbox.
provisioning_state	Where the domain is in the security check: screening, review, ready or rejected.
max_mailboxes, storage_quota_mb	Per-domain caps on mailbox count and total storage (in MB), which can be set through the API or the WHMCS module. null means no cap is set.
mailboxes_used, storage_allocated_mb, storage_used_mb	Current usage on the domain. Storage figures are in MB: allocated is the mailbox sizes you set, used is the mail actually stored.

Only a domain whose provisioning_state is ready accepts new mailboxes. screening and review mean the domain has not cleared the security check yet, and rejected means it did not pass, so mailboxes cannot be created on it.

Results come 15 per page by default. Add per_page or page to the query string to change that, for example ?per_page=50&page=2. To look up a single domain, add domain_name=example.com to the query string, or send GET to https://system.atriomail.com/api/v1/domains/42 with the domain's id.

The list arrives as one n8n item with a data array inside it. To handle each domain separately, split that array into items first, for example with n8n's Split Out node on the data field.

Step 4: Create a mailbox with a POST request

Add a second HTTP Request node that sends POST to https://system.atriomail.com/api/v1/mailboxes with a JSON body that names the domain, the mailbox, a display name and a password.

Method:             POST
URL:                https://system.atriomail.com/api/v1/mailboxes
Authentication:     Header Auth credential (X-API-KEY)
Send headers:       on
Header:             Accept: application/json
Send body:          on
Body content type:  JSON

The body settings appear once the node's send-body option is switched on. Choose JSON as the content type, choose to enter the body as JSON, and paste the body below. Labels vary a little between n8n versions.

The JSON body, with placeholders to replace:

{
  "domain_id": 42,
  "local_part": "info",
  "name": "Info Desk",
  "password": "YOUR_MAILBOX_PASSWORD"
}

That creates info@example.com on the domain with id 42. In n8n you can fill domain_id from the previous node's output with an expression instead of typing the number, for example {{ $json.id }} when each incoming item is one domain. The node sends one request per incoming item, so narrow the list to the domain you mean first, for example by adding ?domain_name=example.com to the GET in step 3. Otherwise the POST runs once for every domain in the list and creates, and bills, an info@ mailbox on each of them. The same request with curl:

curl -X POST https://system.atriomail.com/api/v1/mailboxes \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"domain_id": 42, "local_part": "info", "name": "Info Desk", "password": "YOUR_MAILBOX_PASSWORD"}'

Body fields

Field	Required	Notes
domain_id	Yes	The domain's id from step 3.
local_part	Yes	The part before the @. Up to 64 characters: letters, digits, dots, underscores, hyphens, plus signs and percent signs.
name	Yes	The mailbox's display name, up to 255 characters.
password	Yes	At least 8 characters. Use a long, unique password.
quota	No	Mailbox size in MB. Leave it out to get the included 15 GB (15360 MB); any value from 1 up to 15360 is raised to 15360. A larger size adds storage, billed on the size you set in 5 GB blocks at $0.60 per block per month. A partial block rounds up to a whole block, so 20480 (20 GB) and 18000 are both $1.99 a month. Keep it at or below 102400 (100 GB, the panel maximum). The API does not check that maximum for you, and storage is billed on the size you send, so check this value before the workflow runs.
active	No	true or false. Defaults to true. An inactive mailbox is still billed.

A successful response

A successful request returns status 201 with the new mailbox in data. A trimmed example:

{
  "message": "Mailbox created successfully",
  "data": {
    "id": 118,
    "username": "info@example.com",
    "name": "Info Desk",
    "domain": "example.com",
    "domain_id": 42,
    "active": true,
    "quota": 15360,
    "sync_status": "synced"
  }
}

Only 201 means the mailbox was created and set up. For any other status, read the message field in the response, and the errors field when it is there.

Other responses and what they mean

Status	Meaning	What to do
207	The mailbox record was saved, but the mail server did not confirm the new mailbox.	Do not resend the same request: the address now exists, so a retry answers 422. Contact support with the mailbox id from the response. The saved mailbox counts toward your bill until it is deleted, so mention that too.
401	The API key is missing or not valid (wrong, switched off or expired).	Check the Header Auth credential's name and value.
403	The account behind the key may not create this mailbox, for one of three reasons: the domain belongs to an account the key cannot manage; the key belongs to an account with the Regular User role, which can list domains but cannot create mailboxes through the API; or the account has to verify its identity first. A customer account created through the API gets the Regular User role unless the request sets another role, and customer accounts created by the WHMCS module get it too.	Use a key from an account that can manage the domain and is not a Regular User account. For a customer account created through the API, that is the reseller account that created it. If the message asks for identity verification, finish it in the panel.
409	The domain has not cleared its security check.	Read provisioning_state. For screening, check again after a pause. For review, wait for the review to finish. For rejected, the domain will not become ready on its own, so stop the workflow and contact support if you believe the decision is a mistake. Do not retry in a tight loop.
422	Validation failed: a required field is missing or invalid, the domain id does not exist, the mailbox already exists, or the domain has reached its mailbox or storage cap.	Read message and errors in the response and fix the body.
429	Too many requests: more than 30 in a minute, or too many recent attempts with a wrong key.	Wait before trying again, then slow the workflow down (step 5). A refusal for going over 30 in a minute carries a Retry-After response header with the seconds to wait. A lockout after wrong-key attempts gives the seconds in the retry_after field of the response body instead.

By default, n8n's HTTP Request node stops the workflow when the API answers with an error status. If you want to branch on the status instead, the node's response options can, for example, include the status code in its output and keep going on errors. The exact option names depend on your n8n version.

A 207 is not an error status, so n8n carries on as if the mailbox had been created. Check the response before the next step, for example with an If node that continues only when data.sync_status equals synced, and send anything else to a branch that alerts you.

Step 5: Stay under 30 requests per minute

The API allows up to 30 requests per minute, so pace any workflow that loops over many domains or mailboxes.

Every call counts toward the limit, including the GET from step 3 and any retries. A workflow that looks up a domain and then creates a mailbox makes two requests per item, not one.

One way to pace it in n8n, for example: process items in small batches with a Loop Over Items node, and put a Wait node inside the loop. Count requests, not items. Batches that send at most 10 requests, followed by a 30-second wait, keep you comfortably under the limit: that is 10 items per batch when each item makes one request, or 5 when it makes two. The limit is counted per sending IP address, not per API key, so every workflow on the same n8n server shares it: keep their combined rate under 30 requests per minute. On a hosted n8n plan, other n8n users' requests may leave from the same addresses as yours, so leave extra headroom. If you turn on retries for the HTTP Request node, leave a pause between attempts, because each retry is another request.

For a one-off batch, the control panel may be simpler: it can create many mailboxes on one domain in a single step (one username per line, one domain per batch, and each mailbox is billed).

Limits to plan around

• No native node. There is no Atriomail node or ready-made Atriomail integration in n8n. Everything on this page uses the generic HTTP Request node.
• Your workflow has to ask. The REST API has no way to subscribe to mailbox or domain changes. A workflow that needs current information reads it from the API when it runs, for example on a schedule, and those reads count toward the 30 requests per minute.
• One kind of key. An API key carries the full permissions of the account that created it. Store it only in n8n's credential store, and switch it off or regenerate it in the panel if it may have leaked.

What else the API covers

The same key and header work for the rest of the REST API, which covers domains, mailboxes, forwarders, catch-alls, mailbox storage, customer accounts, IMAP migration jobs, DNS record checks and single-use sign-in links. It does not cover every screen in the control panel.

• If you also sell mailboxes through WHMCS, note that mailboxes created through the API do not sync into WHMCS billing on their own. See the WHMCS module page for how that module bills.
• A domain also needs its mail DNS records before its mailboxes can receive mail. If you connect a Cloudflare or Namecheap account first, let Atriomail import its domain list, and then add one of those domains, Atriomail can write the MX, SPF, DMARC, autodiscover and autoconfig records plus the DKIM key into that zone once the domain passes the security check. Writing the MX record moves that domain's mail, so add the domain when you are ready to switch; the Cloudflare and Namecheap DNS guide walks through the order. Every domain also has a DNS Setup dialog in the panel that lists its records to add at your DNS host (MX, SPF, DMARC, and the DKIM key and Amazon SES verification records once generated), each with a copy button. Do not count on the Amazon SES verification records being written for you, even on Cloudflare or Namecheap, and on any other DNS host add all of the records from that dialog. Anyone can check a domain's public MX, SPF, DKIM (using the selector you enter) and DMARC records with the free DNS checker.
• The integrations page lists the other ways to connect Atriomail, and the email glossary defines common email hosting terms.

Questions about a workflow you are building? Contact us or write to support@atriomail.com.