Multi-channel messaging API supporting Email, SMS, and Push notifications with multiple carrier integrations.

Overview

Authentication

POST /api/admin/login

Request Body

{
  "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
  "password": "your_password"
}

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
    "name": "Admin User",
    "role": "admin"
  },
  "expires_in": 86400
}

GET /api/admin/me

Returns current admin user details.

Email Endpoints

POST /api/emails

Parameters

Field	Type	Required	Description
from_email	string	Required	Sender email address
to_email	string	Required	Recipient email address
subject	string	Required	Email subject (max 500 chars)
html	string	Optional	HTML content (required if no text)
text	string	Optional	Plain text content (required if no html)
carrier	string	Optional	ses, brevo, sendgrid, smtp
cc	string|array	Optional	CC recipients
bcc	string|array	Optional	BCC recipients
reply_to	string	Optional	Reply-to address
headers	object	Optional	Custom headers
metadata	object	Optional	Custom metadata

POST /api/emails/bulk

Max 100 emails per request.

Request Body

{
  "emails": [
    {
      "from_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "to_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "subject": "Newsletter",
      "html": "<p>Content</p>"
    },
    {
      "from_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "to_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
      "subject": "Newsletter",
      "html": "<p>Content</p>"
    }
  ],
  "carrier": "ses"
}

Response

{
  "total": 100,
  "success_count": 98,
  "failure_count": 2,
  "results": [...]
}

GET /api/emails

Parameters

Parameter	Type	Default	Description
status	string	-	queued, sending, sent, delivered, bounced, failed
limit	integer	50	Results per page
offset	integer	0	Pagination offset
domain_id	integer	-	Filter by domain
from_date	date	-	Filter by date (ISO8601)
to_date	date	-	Filter by date (ISO8601)

GET /api/emails/{uuid}

Response

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "delivered",
    "to_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
    "from_email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.",
    "subject": "Welcome",
    "carrier": "brevo",
    "sent_at": "2025-01-22T10:00:00Z",
    "opened_at": "2025-01-22T10:15:00Z"
  }
}

GET /api/emails/{uuid}/events

Returns tracking events (sent, delivered, opened, clicked, bounced).

GET /api/carriers

Returns configured carriers and their status.

SMS Endpoints

POST /api/sms

Parameters

Field	Type	Required	Description
to	string	Required	Phone number (E.164 format)
message	string	Required	Message content (max 1600 chars)
carrier	string	Optional	twilio or topmessage
template_id	integer	Optional	Use template
variables	object	Optional	Template variables

POST /api/sms/bulk

Max 100 recipients per request.

Request Body

{
  "recipients": ["+33612345678", "+33687654321"],
  "message": "Flash sale! 20% off today only.",
  "carrier": "topmessage"
}

GET /api/sms

Query parameters: status, limit, offset, from_date, to_date

GET /api/sms/stats

Returns SMS delivery statistics.

GET /api/sms/templates

Returns all SMS templates.

POST /api/sms/templates

POST /api/sms/templates/{id}/render

Push Notifications

POST /api/push

Must have at least title, body, OR data.

Parameters

Field	Type	Required	Description
device_token	string	Required	Device FCM/APNs token
title	string	Optional	Notification title
body	string	Optional	Notification body
data	object	Optional	Custom data payload
carrier	string	Optional	fcm or onesignal

POST /api/push/bulk

Max 500 device tokens per request.

POST /api/push/topic

POST /api/push/devices

GET /api/push/devices

Query parameters: limit, offset, status

DELETE /api/push/devices

PUT /api/push/devices/{id}/topics

Domains & Addresses

POST /api/domains

Response

{
  "data": {
    "id": 1,
    "domain": "mail.example.com",
    "status": "pending"
  },
  "verification_instructions": {
    "dns_records": [
      {"type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none"},
      {"type": "TXT", "name": "mail._domainkey", "value": "..."}
    ]
  }
}

GET /api/domains

Query parameters: status (pending, verified, failed, suspended)

POST /api/domains/{id}/verify

Checks DNS records and updates domain status.

Response

{
  "verified": true,
  "dns_records_status": {
    "dmarc": "valid",
    "dkim": "valid",
    "spf": "valid"
  }
}

POST /api/domains/{domainId}/addresses

GET /api/addresses/{id}/limits

Response

{
  "data": {
    "daily_used": 150,
    "daily_limit": 1000,
    "monthly_used": 4500,
    "monthly_limit": 30000,
    "allowed": true
  }
}

Mailing Lists

GET /api/lists

Query parameters: status, folder_id, search

POST /api/lists

GET /api/lists/{id}/subscribers

Query parameters: limit, offset, status

POST /api/lists/{id}/subscribers

POST /api/lists/{id}/subscribers/bulk

GET /api/import/brevo/test

Tests the Brevo API connection.

GET /api/import/brevo/lists

Returns available lists from Brevo account.

POST /api/import/brevo/lists

POST /api/import/brevo/full

Imports all lists and contacts from Brevo.

Statistics

GET /api/stats/overview

Response

{
  "data": {
    "total_sent": 15000,
    "total_opened": 8500,
    "total_clicked": 2100,
    "total_bounced": 150
  }
}

GET /api/stats/daily

Parameters

Parameter	Type	Default	Description
days	integer	30	Number of days (max 90)
domain_id	integer	-	Filter by domain

Response

{
  "data": [
    {
      "date": "2025-01-22",
      "sent": 500,
      "delivered": 495,
      "opened": 280,
      "clicked": 75,
      "bounced": 5
    }
  ]
}

GET /api/stats/carriers

Statistics broken down by carrier.

GET /api/stats/totals

Response

{
  "data": {
    "total_emails": 50000,
    "total_sms": 5000,
    "total_push": 25000,
    "active_domains": 5
  }
}

Queue Management

GET /api/queue/stats

Response

{
  "data": {
    "queued": 150,
    "processing": 10,
    "failed": 5,
    "total": 165
  }
}

GET /api/queue/scheduled

Returns emails scheduled for future delivery.

GET /api/queue/failed

Query parameters: limit (default 50, max 100)

PUT /api/queue/{emailId}/reschedule

scheduled_at must be in the future.

POST /api/queue/{queueId}/retry

Retries a failed queue job.

DELETE /api/queue/{emailId}

Cancels a scheduled email before it's sent.

Notification Channels

Configure external notification channels (Slack, Google Chat) for delivery events.

GET /api/notifications/channels/types

Response

{
  "channel_types": ["google_chat", "slack"],
  "available_events": [
    "email.sent", "email.delivered", "email.bounced",
    "sms.sent", "sms.delivered", "sms.failed",
    "push.sent", "push.delivered"
  ]
}

POST /api/notifications/channels

POST /api/notifications/channels/{id}/test

Sends a test message to the notification channel.

POST /api/notifications/channels/{id}/toggle

Enables or disables the notification channel.

Webhooks (Carrier Callbacks)

These endpoints receive delivery status updates from carriers. No authentication required.

Error Handling

Code	Meaning
200	OK - Successful GET/PUT request
201	Created - Successful POST request
400	Bad Request - Invalid input
401	Unauthorized - Missing/invalid API key
403	Forbidden - Insufficient permissions
404	Not Found
409	Conflict - Resource already exists
422	Validation Error
429	Rate Limit Exceeded
500	Server Error

{
  "success": true,
  "data": { },
  "message": "Optional success message"
}