Admin API

Platform admins are users with is_admin: true. They can impersonate users, manage polls, list users, and send transactional email broadcasts via SendGrid.

The is_admin flag is returned on sign-in and token validation responses.

List users

GET /api/v1/admin/users
Authorization: Bearer <admin_token>

Query parameters:

Parameter	Type	Description
query	string	Filter by email or name
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 25, max: 100)

Response:

{
  "data": [
    {
      "id": 1,
      "email": "user@example.com",
      "name": "Jane Doe",
      "email_verified": true
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 4,
    "total_count": 87,
    "all_users_count": 120
  }
}

all_users_count is the total number of active users and is useful for a "select all users" control in the admin UI.

Send transactional email

Sends one transactional email per recipient using SendGrid (not the marketing/contacts API). Delivery is queued in the background.

POST /api/v1/admin/emails
Authorization: Bearer <admin_token>
Content-Type: application/json

Send to selected users

{
  "email": {
    "subject": "Important update",
    "content": "<p>Hi {{name}},</p><p>We have an update for you.</p>",
    "user_ids": [1, 2, 3]
  }
}

Send to all active users

{
  "email": {
    "subject": "Important update",
    "content": "<p>Hi {{name}},</p><p>We have an update for you.</p>",
    "send_to_all": true
  }
}

Field	Type	Required	Description
subject	string	Yes	Email subject line
content	string	Yes	HTML email body
user_ids	array	No*	User IDs to receive the email
send_to_all	boolean	No*	When true, sends to every active user

* Provide either user_ids (non-empty) or send_to_all: true.

Optional placeholders in content:

• — recipient name
• — recipient email

Response (202 Accepted):

{
  "message": "Email broadcast queued successfully",
  "recipient_count": 120,
  "send_to_all": true
}

Related endpoints

• Polls API — admin poll management
• GET/POST /api/v1/impersonations — impersonate users (admin only)
• DELETE /api/v1/impersonation — end impersonation