Think of it this way: an email marketing campaign is like a flyer you print and hand out to a whole crowd. A transactional send is like a personal letter written and sent the exact moment something happens — someone made a purchase, signed up, or asked to reset their password.
In this guide we connect your system to arrobaMail to send those automatic emails. It's a technical tutorial (you'll see code), but it's explained so anyone can follow what each step does. If you know a bit of HTTP, you can have it running in an afternoon.
Before you start
- An arrobaMail account with a verified sender (SPF/DKIM) and a list.
- Access to your system's backend (or your developer), to make HTTP calls.
- Your arrobaMail username and password to get the API token.
The 7 steps
- 1
What a transactional send actually is
An individual, automatic email triggered by a specific event, not a list.
- 2
The three ways to send them
Direct API, event-based automation, or webhooks: what changes is who builds the email and who fires it.
- 3
Method 1 — Direct API
Your system builds the HTML and hands it to arrobaMail to deliver.
- 4
Method 2 — Event-based automation
The email lives inside arrobaMail; your system just registers the event that fires it.
- 5
Method 3 — Webhooks
The other way around: arrobaMail notifies your system when a flow reaches a Webhook node.
- 6
Common mistakes and how to fix them
The usual trip-ups: the event name that didn't save, the 404, the expired token.
- 7
Reference and where to go next
A quick-reference table of endpoints and where to dig deeper.
1. What a transactional send actually is
A transactional email is an individual, automatic email triggered by a specific event. It doesn't go to a list — it has one specific recipient and one exact moment. The everyday ones:
- Purchase confirmation — "Your order #12345 is confirmed. Arriving Tuesday."
- Verification code (OTP) — "Your code is 482931. Expires in 5 minutes."
- Invoice — "Here's your invoice for $10.15."
- Reminder — "Your appointment is tomorrow at 10:00."
One key distinction: arrobaMail doesn't replace your system. Your system is still the one that detects the event. arrobaMail is the specialized delivery service: it takes the instruction and sends the email with SPF/DKIM authentication, bounce handling, and per-provider optimization (Gmail, Outlook, Yahoo). You handle the "when"; arrobaMail handles "making sure it arrives."
2. The three ways to send them
arrobaMail offers three mechanisms. What changes between them is who builds the email and which direction the conversation flows:
Direct API
builds and sends the email
Your system builds the email's HTML and sends it to arrobaMail to deliver.
- Builds the email:
- Your system
- When to use it:
- The content is generated in your backend: invoices, reports with variable data.
Event-triggered automation
logs an event
The email is already built in arrobaMail; your system just fires the event and arrobaMail sends it.
- Builds the email:
- arrobaMail
- When to use it:
- The email is already designed (with the editor or with AI). Your system just says "send it."
Webhooks
POST to your server
The other way around: arrobaMail notifies your system with a POST when the flow reaches the Webhook node.
- Builds the email:
- —
- When to use it:
- You need arrobaMail to notify your backend whenever a flow runs.
In short: if the content gets generated in your backend (an invoice with variable data), use direct API. If the email is already designed inside arrobaMail and your system just needs to fire it, use event-based automation. And if you need arrobaMail to notify your system when something happens, use webhooks. Let's look at all three.
3. Method 1 — Direct API
Your code builds the complete email (HTML, subject, sender) and hands it to arrobaMail. There's no automation involved — your system decides everything.
Step 1 — Get the JWT token. It's a temporary pass that authorizes your calls.
POST https://envios.arrobamail.com/v3/api/auth/getToken
Content-Type: application/json
{ "username": "your_username", "pass": "your_password", "rememberMe": false, "locale": "en" }
You get back { "token": "eyJhbGci...", "expires": ... }. Save it — it goes in the Authorization: Bearer {token} header on every subsequent call.
Step 2 — Try a test send (doesn't count against your quota): send yourself a copy to check it looks right.
POST /campaigns/test
Authorization: Bearer {token}
{ "email": "[email protected]", "subject": "Confirmation #12345",
"html": "<html>...</html>", "fromname": "Your Company", "frommail": "[email protected]" }
Step 3 — Send the real email. This queues immediate delivery.
POST /campaigns
Authorization: Bearer {token}
{ "campname": "Confirmation_12345", "asunto": "Your order is confirmed",
"html": "<html>...</html>", "fromname": "Your Company", "frommail": "[email protected]",
"listid": ["YOUR_LIST_ID"], "preheader": "Thanks for your purchase.",
"tracklinks": 1, "trackreads": 1 }
You get back an encid (the campaign's identifier). Save it.
Step 4 — Check the result using that encid:
GET /campaigns/{encid}/stats/subscriber-actions
It tells you whether the email was delivered, opened, clicked, or bounced.
When to use it: the content is generated in your backend with variable data — invoices, reports, receipts. Your code has full control over the HTML.
4. Method 2 — Event-based automation
Here the email is already built inside arrobaMail. Your system just says "send this to this person now." arrobaMail finds the automation, swaps in the variables, and sends. It has two parts.
Part A — Set it up on the platform (one time only)
- Create the automation: Automation › New Automation.
- Choose the «Custom event» trigger (the one that responds to external calls).
- Type the exact event name — for example,
course_confirmation. It's case-sensitive:Course_Confirmationis not the same thing. Make sure the name shows up printed inside the blue node. - SAVE. (Yes, in caps — it's the step most often forgotten, and the one that causes most of the problems.)
- Add the «Send email» action below the trigger and choose the content (editor, AI, or template).
- Define the re-entry policy (what happens if the same contact triggers the event more than once): Never (welcome emails), Always (invoices, reminders), After completing, or With a waiting period.
- Activate the flow.
Part B — Call it from your system (on every event)
Get the token (same as in Method 1), then register the event. It's a GET with the data in the URL:
GET /events/record?eventName=course_confirmation&[email protected]&listid=YOUR_LIST_ID&pf_course=Marketing&pf_date=06/20/2026
Authorization: Bearer {token}
What each piece is:
- eventName — the exact trigger name from step 3 (identical, including case).
- email — the recipient; must exist as an Active subscriber on the list (if it's Pending due to double opt-in, it won't fire).
- listid — the list's ID (an encrypted string, not a number).
- pf_* — dynamic variables for the email without storing them on the contact. In the template they're used as
{{{pf_course}}}.
If it responds with { "status": "success", ... }, the engine is already processing the event.
When to use it: the email is already designed in arrobaMail (with the editor or with AI) and your system just needs to trigger it. Less code on your end.
5. Method 3 — Webhooks
The two methods above have your system talking to arrobaMail. This one is the other way around: when a subscriber passes through a Webhook node inside an automation, arrobaMail makes a POST to a URL of yours with the contact's data. It's how arrobaMail can trigger logic in your backend (grant access, issue an invoice).
- Create the automation with a «Custom event» trigger (same as Method 2), but instead of «Send email», add a Webhook action node.
- Configure the URL for your server (it must be HTTPS).
- Program the receiver: your server listens for the
POST, reads the JSON, and responds withHTTP 200.
<?php // webhook-handler.php
$payload = json_decode(file_get_contents("php://input"), true);
if (isset($payload["email"])) {
$email = $payload["email"];
// Your logic here: grant access, issue an invoice, etc.
}
http_response_code(200);
echo json_encode(["status" => "ok"]);
Tip: the payload structure can vary. In your early tests, log the entire body to see exactly which fields arrive before you build your logic around them.
6. Common mistakes and how to fix them
- The event registers but the email never arrives. Almost always: the event name never saved in the node. The flow shows "Active" but the trigger is empty. → Edit the flow, retype the name, confirm it shows up inside the blue node, and SAVE.
- HTTP 404 — subscriber_not_found. The
emaildoesn't exist as an active subscriber on thatlistid. → Add it as a subscriber before calling the event (and make sure it's not Pending). - HTTP 401 — invalid or expired token. → Request a new token and check the header reads exactly
Authorization: Bearer {token}(with the space after Bearer). - The email arrives more than once. → There are duplicate flows on the same event, or the re-entry policy is set to "Always" and your code is calling it too often. Pause the duplicates and review your code.
7. Reference and where to go next
The endpoints you used, at a glance:
| Endpoint | What it's for |
|---|---|
POST /auth/getToken |
Get the authentication token. |
POST /campaigns/test |
Send a test email (direct API). |
POST /campaigns |
Send the real email (direct API). |
GET /events/record |
Register an event and trigger the automation. |
GET /campaigns/:encid/stats/subscriber-actions |
Check whether an email was delivered or opened. |
For full detail on every endpoint — parameters, responses, and examples in curl, Node, PHP, and Python — see the API reference. For the full picture of every way to integrate (including AI via MCP), see connecting arrobaMail to your systems and the API page.
Next steps
- See the full integration picture in connecting arrobaMail to your systems.
- Go deeper on each endpoint in the API reference.
- If you want to run your account through an AI assistant, check out MCP.