REST API Authentication and Endpoints

What this is for#

The complete reference for AcelleMail's REST API. Use this alongside the Getting Started guide — this article is the lookup table.

Base URL: https://mail.example.com/api/v1/ Auth: token (see below) — every authenticated route requires it Format: request Content-Type: application/json (POST/PATCH/PUT) + Accept: application/json on every request

Authentication#

AcelleMail uses Laravel's auth:api driver — a simple bearer-token scheme.

Get a token#

Two methods:

• UI: Profile → API Token → Generate / Copy
• API: POST /api/v1/user/login (unauthenticated):

  POST /api/v1/user/login
  email=you@example.com&password=Yours
  → 200 OK
  { "api_token": "..." }
  

Send the token#

Either is valid:

Scoping rules#

A token is tied to one user, and inherits their scope:

• Customer user token → can read/write only resources owned by that customer (their lists, campaigns, subscribers, automations)
• Admin user token → can additionally hit admin-only endpoints (/customers, /subscriptions, /sending_servers create/edit)

You cannot impersonate another user. To act as a customer, log in as that customer and use their token.

Conventions#

• UIDs vs IDs: every resource has both an integer id (DB primary key) and a string uid (URL-safe, opaque). Routes use uid (e.g. /lists/{uid}/subscribers). Responses include both.
• Pagination: list endpoints return paginated responses with data, current_page, per_page, total, last_page. Use ?page=2&per_page=50 to navigate (max per_page typically 100).
• Filtering: most list endpoints support ?filter[field]=value style filters; specific allowed filters vary per endpoint.
• Errors: standard Laravel error responses — 422 for validation, 404 for missing, 401 for auth, 403 for forbidden, 500 for server error. Body includes message + (on 422) errors[].
• Timestamps: ISO 8601 UTC strings (2026-05-16T14:32:11.000000Z).

Resources#

Public (unauthenticated)#

Subscribers — public signup form#

POST /api/v1/public/subscribers
Content-Type: application/json
{
  "MAIL_LIST_UID": "abc123",
  "EMAIL": "alice@example.com",
  "FIRST_NAME": "Alice",
  "LAST_NAME": "Doe",
  ...custom fields per the list schema...
}
→ 200 OK
{ "uid": "subUID", "status": "subscribed" }

The only public endpoint. Use it for signup forms on your marketing site — no token needed.

Add rate limiting at the nginx level to defend against spam bots (see post-install hardening).

Authentication + identity#

Lists#

Create example:

POST /api/v1/lists
{
  "name": "Newsletter Q2",
  "from_email": "news@example.com",
  "from_name": "Example Team",
  "default_subject": "Update from Example",
  "contact": {
    "company": "Example Co",
    "address_1": "123 Main St",
    "city": "San Francisco",
    "country_id": 234,
    "url": "https://example.com"
  }
}
→ 201 Created
{ "uid": "newListUID", "name": "Newsletter Q2", ... }

Subscribers#

Add subscriber:

POST /api/v1/subscribers
{
  "MAIL_LIST_UID": "abc123",
  "EMAIL": "alice@example.com",
  "FIRST_NAME": "Alice"
}
→ 201 Created
{ "uid": "subUID", "email": "alice@example.com", "status": "subscribed" }

Campaigns#

Automations#

The api/call endpoint is what powers the API trigger feature — your external app POSTs to this URL to begin an automation flow for a specific subscriber.

Sending servers#

Customers (admin only)#

Subscriptions (admin only)#

Notifications (sending-provider webhook inbound)#

These endpoints receive webhooks from the sending provider (SES SNS, Mailgun, SendGrid event hooks) — you don't typically call them directly:

File upload + management#

System / admin#

Common patterns#

Paginated list#

# Get page 2, 50 per page
curl -H "Authorization: Bearer $TOKEN" \
  "https://mail.example.com/api/v1/subscribers?page=2&per_page=50&filter[list_uid]=abc123"

Create then add many subscribers#

# 1. Create the list
LIST_UID=$(curl -s -X POST ... /api/v1/lists -d '...' | jq -r .uid)

# 2. Bulk-add subscribers (loop or batch via the import flow for > 1000)
for email in $(cat emails.txt); do
  curl -X POST ... /api/v1/subscribers \
    -d "MAIL_LIST_UID=$LIST_UID&EMAIL=$email"
done

For > 1000 subscribers, use the list-import flow — much faster than per-subscriber POST.

Send a one-off campaign via API#

# 1. Create the campaign
CAMP_UID=$(curl -s -X POST ... /api/v1/campaigns -d '{
  "name": "Q2 Newsletter",
  "type": "regular",
  "subject": "Our June updates",
  "from_email": "news@example.com",
  "from_name": "Example",
  "html_content": "<h1>Hi {FIRST_NAME}</h1>...",
  "mail_list_uid": "abc123",
  "sign_dkim": true,
  "track_open": true,
  "track_click": true
}' | jq -r .uid)

# 2. Start sending
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://mail.example.com/api/v1/campaigns/$CAMP_UID/run"

Trigger an automation#

# Customer X just bought a product; start them on the post-purchase flow
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "EMAIL": "buyer@example.com",
    "FIRST_NAME": "Buyer",
    "product_name": "Widget Pro",
    "purchase_amount": 99.00
  }' \
  https://mail.example.com/api/v1/automations/AUTOMATION_UID/api/call

The custom fields (product_name, purchase_amount) are available as merge tags inside the automation's emails.

Error reference#

A typical 422 looks like:

{
  "message": "The given data was invalid.",
  "errors": {
    "EMAIL": ["The EMAIL field is required."],
    "MAIL_LIST_UID": ["The selected MAIL_LIST_UID is invalid."]
  }
}

Tips for production use#

• Log every API call's request id (Laravel emits one per request in the response headers) for traceable debugging
• Set request timeout in your client to ≥ 30 seconds — bulk operations (large list creation, campaign run) can take that long
• Retry on 5xx with exponential backoff; don't retry on 4xx (it'll just fail again)
• Never log the token itself — sanitize before logging headers
• Rotate the token quarterly by regenerating in the UI

FAQ#

Is the API stable across Acelle versions? v1 has been stable across multiple major releases. Additive changes (new fields, new endpoints) are common; breaking changes are rare and pre-announced in acellemail-updates.

Is there an OpenAPI / Swagger spec? Not officially shipped. Build by introspecting routes/api.php and generating from controller signatures.

Does the API support GraphQL? No — REST only.

Can the API run a campaign for me without an existing list? No — campaigns must reference a mail_list_uid that already exists. Create the list first.

What's the difference between id and uid? id is the DB primary key (integer); uid is the URL-safe string identifier. Always use uid in routes; you'll see both in responses.

Webhooks? Different system from the API. See Webhook Events Reference for outbound events your app can subscribe to.

Related articles#

• Getting Started with the AcelleMail REST API — the 5-minute kickoff (start here if you haven't)
• Webhook Events Reference — outbound events
• Extending AcelleMail Source Code — when the API isn't enough
• Using API Triggers for Custom Automation Workflows — the /automations/{uid}/api/call use case
• Zapier Integration Guide — no-code API client
• Importing Contacts: CSV Best Practices and Field Mapping — for bulk subscriber adds
• Setting Up AcelleMail as a SaaS Platform — per-customer API tokens
• Post-Install Hardening Checklist — securing the API surface