HTTP clients: connecting your system to the API from any language

The arrobaMail API is REST over HTTPS with JSON: there's no mandatory SDK or proprietary protocol. If your language can make an HTTP request, it can talk to the API. This page is the reference for how to connect — base URL, authentication, headers, errors, and limits —; if what you want is to make your first call in three steps, start with the quickstart.

Never put your API Key or your token in the front-end or in a public repository. Store them as server-side environment variables. In the examples we use the placeholders TU_USUARIO, TU_PASSWORD, and TU_TOKEN.

Base URL

Every route hangs off the base, on your sending server:

https://{servidor}.arrobamail.com/v3/api/

The {servidor} is the host we assigned you (the API is multi-server). You'll find it in your panel; always use yours, not a generic one. Every endpoint in the reference is relative to that base — for example GET /v3/api/campaigns.

Authentication: JWT token

Authentication is via JWT. The flow has two steps:

1. Request a token with your credentials at POST /auth/getToken.
2. Send that token in the Authorization: Bearer <token> header on every subsequent request.

# 1) Obtener el token
curl -X POST "https://{servidor}.arrobamail.com/v3/api/auth/getToken" \
  -H "Content-Type: application/json" \
  -d '{"username":"TU_USUARIO","password":"TU_PASSWORD"}'
# → { "token": "eyJhbGciOi..." }

The token has a lifespan: when it expires, request a new one. Don't hardcode it — keep it in memory and refresh it when a response returns 401.

Headers you'll use

Header	Value	When
Authorization	Bearer TU_TOKEN	On every authenticated request
Content-Type	application/json	When sending a body (POST/PUT/PATCH)
Accept	application/json	Recommended always

Examples by client

Same operation — listing campaigns — from four clients. The syntax changes, not the logic: token in the header and JSON back and forth.

# curl
curl "https://{servidor}.arrobamail.com/v3/api/campaigns" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Accept: application/json"

// Node.js (fetch nativo, v18+)
const res = await fetch('https://{servidor}.arrobamail.com/v3/api/campaigns', {
  headers: {
    Authorization: `Bearer ${process.env.ARROBAMAIL_TOKEN}`,
    Accept: 'application/json',
  },
})
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const data = await res.json()

// PHP (cURL)
$ch = curl_init('https://{servidor}.arrobamail.com/v3/api/campaigns');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('ARROBAMAIL_TOKEN'),
    'Accept: application/json',
  ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

# Python (requests)
import os, requests

resp = requests.get(
    "https://{servidor}.arrobamail.com/v3/api/campaigns",
    headers={
        "Authorization": f"Bearer {os.environ['ARROBAMAIL_TOKEN']}",
        "Accept": "application/json",
    },
    timeout=15,
)
resp.raise_for_status()
data = resp.json()

For a write operation (creating something), the pattern is the same plus Content-Type: application/json and the body in JSON. The detail of each endpoint — method, parameters, and body shape — is in the reference.

Error handling

The API uses standard HTTP status codes. Program your client to distinguish between them:

Code	Means	What to do
200 / 201	OK / created	Continue
400	Malformed request	Check the body and parameters
401	Missing or expired token	Request a new token and retry
403	No permission for that operation	Check your account's scope
404	Resource doesn't exist	Check the ID / route
429	Too many requests	Wait and retry with backoff
5xx	Server error	Retry with backoff; if it persists, let us know

Always treat the error response body as JSON: it usually carries a message explaining what went wrong. Don't assume an empty 2xx is an error.

Rate limits and best practices

• Respect the limits. On a 429, don't hammer the endpoint: wait and retry with exponential backoff (1s, 2s, 4s…).
• Reuse the token while it's still valid; don't request a new one on every request.
• Paginate long listings instead of fetching everything at once.
• Timeouts and retries in your client for network errors and 5xx.
• Idempotency: when creating resources, save the ID returned so you don't duplicate on retry.

Testing without writing code: Postman / Insomnia

To explore the API before you start coding, any graphical client works:

1. Create an environment with two variables: base (https://{servidor}.arrobamail.com/v3/api) and token.
2. Make the POST {{base}}/auth/getToken call with your credentials and save the token into the variable.
3. On the rest of the requests, set the Authorization: Bearer {{token}} header at the collection level.

That way you test endpoints, see the real responses, and then carry over what worked into your code.

Next steps

• Your first call, step by step? The API quickstart.
• The catalog of endpoints? The reference.
• Reacting to events (opens, purchases) instead of polling? Check out webhooks.
• Operating with an AI assistant without writing code? Integration via MCP.