API overview

Authenticate and integrate Mailivate with your application — subscribers, tags, segments, automations, and transactional mail.

The Mailivate REST API lets your application manage lists and subscribers, apply tags, trigger automations, and send transactional email. All requests are JSON over HTTPS and authenticated with a personal API token.

Quick start

Create a token — sign in at mailivate.com, open Account → API Tokens, name the token (for example Production app), and copy the value immediately. It is shown only once.
Find your list UUID — call GET /api/email-lists or copy the UUID from the list in the Mailivate UI.
Make a test request — run the example below to confirm authentication works.

export MAILIVATE_URL="https://mailivate.com"
export MAILIVATE_TOKEN="your-api-token"

curl -s "${MAILIVATE_URL}/api/email-lists" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json"

Store MAILIVATE_TOKEN in your application secrets (environment variables or vault). MAILIVATE_URL is always https://mailivate.com for the hosted API. Never commit tokens to source control.

Authentication

Every API request must include:

Header	Value
`Authorization`	`Bearer {your-api-token}`
`Accept`	`application/json`
`Content-Type`	`application/json` (for POST, PUT, PATCH)

Tokens are tied to your Mailivate user account and inherit that account's access to lists and organizations.

Conventions

Base URL

All API requests go to the Mailivate production host:

https://mailivate.com/api

Example: list subscribers on a list:

GET https://mailivate.com/api/email-lists/{email_list_uuid}/subscribers

Resource UUIDs

Lists, subscribers, tags, segments, campaigns, and automations are identified by UUID in URLs, not numeric database IDs.

GET /api/email-lists/{email_list_uuid}
GET /api/subscribers/{subscriber_uuid}
POST /api/automations/{automation_uuid}/trigger

Responses

Successful reads return a JSON resource or paginated collection:

{
  "data": [
    {
      "uuid": "9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "name": "Newsletter",
      "active_subscribers_count": 1240
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 3, "per_page": 15, "total": 42 }
}

Successful deletes return 204 No Content with an empty body.

Validation errors return 422 Unprocessable Entity with an errors object.

Integration examples

The examples below use placeholder UUIDs. Replace them with values from your account.

1. Connect to a list

Fetch all lists your token can access, then read a single list:

# List all email lists
curl -s "${MAILIVATE_URL}/api/email-lists" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json"

# Get one list
curl -s "${MAILIVATE_URL}/api/email-lists/9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json"

PHP (Laravel / Guzzle):

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://mailivate.com',
    'headers' => [
        'Authorization' => 'Bearer '.config('services.mailivate.token'),
        'Accept' => 'application/json',
    ],
]);

$lists = json_decode(
    $client->get('/api/email-lists')->getBody()->getContents(),
    true
);

$listUuid = $lists['data'][0]['uuid'];

2. Subscribe a user to a list

Add a subscriber when someone signs up in your product:

curl -s -X POST "${MAILIVATE_URL}/api/email-lists/9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c/subscribers" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "tags": ["customer", "trial"],
    "extra_attributes": {
      "plan": "pro",
      "signup_source": "web"
    },
    "skip_confirmation": true
  }'

Field	Required	Description
`email`	Yes	Subscriber email address
`first_name`, `last_name`	No	Display name fields
`tags`	No	Array of tag names to apply on subscribe
`extra_attributes`	No	Custom key/value metadata
`skip_confirmation`	No	Set `true` to bypass double opt-in when the list requires confirmation

Response:

{
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email_list_uuid": "9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "tags": ["customer", "trial"],
    "extra_attributes": { "plan": "pro", "signup_source": "web" },
    "subscribed_at": "2026-05-28T10:00:00.000000Z",
    "unsubscribed_at": null
  }
}

Save the returned uuid — you need it to update tags or trigger automations later.

3. Tag or update a subscriber

Replace all tags (sync):

curl -s -X PUT "${MAILIVATE_URL}/api/subscribers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["customer", "paid", "newsletter"]
  }'

Append tags without removing existing ones:

curl -s -X PUT "${MAILIVATE_URL}/api/subscribers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "append_tags": true,
    "tags": ["completed-onboarding"]
  }'

Update profile fields:

curl -s -X PUT "${MAILIVATE_URL}/api/subscribers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "extra_attributes": { "plan": "enterprise" }
  }'

Unsubscribe or resubscribe:

# Unsubscribe
curl -s -X POST "${MAILIVATE_URL}/api/subscribers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/unsubscribe" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json"

# Resubscribe
curl -s -X POST "${MAILIVATE_URL}/api/subscribers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resubscribe" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json"

4. Create tags

Create tags on a list before assigning them to subscribers:

curl -s -X POST "${MAILIVATE_URL}/api/email-lists/9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c/tags" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "paid-customer",
    "visible_in_preferences": true
  }'

List tags on a list:

curl -s "${MAILIVATE_URL}/api/email-lists/9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c/tags" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json"

5. Create a segment from tags

Segments group subscribers by tag rules. Tags must already exist on the list.

curl -s -X POST "${MAILIVATE_URL}/api/email-lists/9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c/segments" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Paying customers",
    "positive_tags": ["customer", "paid"],
    "all_positive_tags_required": true,
    "negative_tags": ["churned"],
    "all_negative_tags_required": false
  }'

Field	Description
`positive_tags`	Subscriber must match these tags
`all_positive_tags_required`	`true` = must have all positive tags; `false` = must have any
`negative_tags`	Subscriber must not match these tags
`all_negative_tags_required`	`true` = must have none of the negative tags; `false` = must not have all

Use segments as campaign or automation audiences in the Mailivate UI.

6. Trigger an automation

Automations with a Webhook trigger can be started from your application — for example after a purchase, course completion, or account upgrade.

The automation must already exist with a Webhook trigger configured. Copy the automation UUID from the automation settings or the trigger card in the UI.

curl -s -X POST "${MAILIVATE_URL}/api/automations/c3d4e5f6-a7b8-9012-cdef-345678901234/trigger" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }'

Requirement	Detail
Trigger type	Automation must have a Webhook trigger
Subscriber UUIDs	Pass an array of subscriber `uuid` values (not email addresses)
List membership	Subscribers must belong to the automation's list and match its segment rules
Subscription status	Only subscribed subscribers are processed

Returns 200 OK with an empty JSON body on success. Returns 400 if the automation has no Webhook trigger.

Typical flow in your app:

User completes checkout
  → POST /api/subscribers/{uuid}  (append tag "purchased")
  → POST /api/automations/{uuid}/trigger  (start post-purchase sequence)

See also Webhooks and automation endpoints for outgoing event webhooks.

7. Send transactional email

Send one-off application email (receipts, password resets, notifications):

curl -s -X POST "${MAILIVATE_URL}/api/transactional-mails/send" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "mail_name": "order-receipt",
    "from": "Store <orders@example.com>",
    "to": "jane@example.com",
    "replacements": {
      "order_number": "ORD-12345",
      "total": "$99.00"
    }
  }'

Or send ad-hoc HTML without a saved template:

curl -s -X POST "${MAILIVATE_URL}/api/transactional-mails/send" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your password reset link",
    "html": "<p>Click <a href=\"https://example.com/reset\">here</a> to reset your password.</p>",
    "from": "App <noreply@example.com>",
    "to": "jane@example.com"
  }'

Field	Required	Description
`from`	Yes	Sender address (optionally `Name <email@domain.com>`)
`to`	Yes	Recipient address or comma-separated list
`mail_name`	No*	Name of a saved transactional template in Mailivate
`subject`	No*	Required when `mail_name` is omitted
`html`	No*	Email body HTML; required for ad-hoc sends without `mail_name`
`replacements`	No	Key/value placeholders merged into the template
`store`	No	Defaults to `true`; set `false` to skip logging the send

* Provide either mail_name or subject.

8. Bulk import subscribers

For large syncs, use the subscriber import API instead of one request per contact:

# 1. Create a draft import
curl -s -X POST "${MAILIVATE_URL}/api/subscriber-imports" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email_list_uuid": "9b3f2c1a-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "subscribers_csv": "email,first_name,last_name,tags\njane@example.com,Jane,Doe,\"customer,vip\"\n",
    "replace_tags": false
  }'

# 2. Start processing (use the import uuid from the response)
curl -s -X POST "${MAILIVATE_URL}/api/subscriber-imports/{import_uuid}/start" \
  -H "Authorization: Bearer ${MAILIVATE_TOKEN}" \
  -H "Accept: application/json"

The CSV must include an email column header. See Importing subscribers for column details.

Endpoint reference

Method	Endpoint	Purpose
`GET`	`/api/email-lists`	List email lists
`GET`	`/api/email-lists/{uuid}`	Get a list
`GET`	`/api/email-lists/{uuid}/subscribers`	List subscribers on a list
`POST`	`/api/email-lists/{uuid}/subscribers`	Add a subscriber
`GET`	`/api/subscribers/{uuid}`	Get a subscriber
`PUT`	`/api/subscribers/{uuid}`	Update subscriber / tags
`DELETE`	`/api/subscribers/{uuid}`	Delete a subscriber
`POST`	`/api/subscribers/{uuid}/unsubscribe`	Unsubscribe
`POST`	`/api/subscribers/{uuid}/resubscribe`	Resubscribe
`POST`	`/api/subscribers/{uuid}/confirm`	Confirm pending subscriber
`GET`	`/api/email-lists/{uuid}/tags`	List tags
`POST`	`/api/email-lists/{uuid}/tags`	Create a tag
`GET`	`/api/email-lists/{uuid}/segments`	List segments
`POST`	`/api/email-lists/{uuid}/segments`	Create a segment
`POST`	`/api/automations/{uuid}/trigger`	Trigger a webhook automation
`POST`	`/api/transactional-mails/send`	Send transactional email
`POST`	`/api/subscriber-imports`	Create bulk import
`POST`	`/api/subscriber-imports/{uuid}/start`	Run bulk import
`GET`	`/api/campaigns`	List campaigns
`GET`	`/api/templates`	List email templates

Error handling

Status	Meaning
`401 Unauthorized`	Missing or invalid API token
`403 Forbidden`	Token valid but no permission for this resource
`404 Not Found`	UUID does not exist or is not accessible
`422 Unprocessable Entity`	Validation failed — check the `errors` object
`406 Not Acceptable`	Transactional send rejected (for example suppressed address)

Example validation response:

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Security

Rotate API tokens periodically and revoke unused tokens under Account → API Tokens at mailivate.com.
Use HTTPS only — never send tokens over plain HTTP.
Scope tokens to the minimum access needed; each token inherits your user permissions.
Do not expose tokens in client-side JavaScript or mobile apps — call the Mailivate API from your backend.