/api/contacts
GETRetrieves a paginated list of contacts with optional search filtering.
Description
The `/api/contacts` endpoint returns a paginated list of your QMail contacts. You can optionally search for specific contacts using the `q` parameter to filter by name or email address.
Pagination Support
Results are paginated to improve performance. Use the `page` and `limit` parameters to navigate through your contacts. The response includes pagination metadata to help you build navigation controls.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | Optional | Page number for pagination (default: 1) |
limit |
integer | Optional | Number of contacts per page. Range: 1-200 (default: 50) |
q |
string | Optional | Search query to filter contacts by name or email |
Response
Returns a JSON object containing the list of contacts and pagination information.
Response Properties
contacts
array
Array of contact objects.
contacts[].user_id
integer
Unique identifier for the contact.
contacts[].first_name
string
Contact's first name.
contacts[].last_name
string
Contact's last name.
contacts[].middle_name
string
Contact's middle name or initial.
contacts[].auto_address
string
Contact's QMail email address.
contacts[].description
string
Optional description or notes about the contact.
contacts[].sending_fee
number
Custom sending fee for this contact.
contacts[].beacon_id
string
Associated beacon identifier.
pagination
object
Pagination metadata.
pagination.page
integer
Current page number.
pagination.limit
integer
Number of contacts per page.
pagination.total
integer
Total number of contacts matching the query.
pagination.total_pages
integer
Total number of pages available.
Example Response
{
"contacts": [
{
"user_id": 1,
"first_name": "Alice",
"last_name": "Johnson",
"middle_name": "M",
"auto_address": "[email protected]",
"description": "Project manager",
"sending_fee": 1.5,
"beacon_id": "beacon-abc123"
},
{
"user_id": 2,
"first_name": "Bob",
"last_name": "Smith",
"middle_name": "",
"auto_address": "[email protected]",
"description": "",
"sending_fee": 0,
"beacon_id": ""
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 2,
"total_pages": 1
}
}Try it out
Examples
JavaScript (fetch)
const API_HOST = 'http://localhost:8080';
async function listContacts(page = 1, limit = 50, search = '') {
try {
const params = new URLSearchParams({
page: page,
limit: limit
});
if (search) {
params.append('q', search);
}
const response = await fetch(`${API_HOST}/api/contacts?${params}`);
const result = await response.json();
console.log(`Page ${result.pagination.page} of ${result.pagination.total_pages}`);
console.log(`Total contacts: ${result.pagination.total}\n`);
result.contacts.forEach(contact => {
console.log(`${contact.first_name} ${contact.last_name}`);
console.log(` Email: ${contact.auto_address}`);
if (contact.description) {
console.log(` Notes: ${contact.description}`);
}
console.log('');
});
} catch (error) {
console.error('Error fetching contacts:', error);
}
}
listContacts(1, 50, 'alice');
cURL
# List first page of contacts
curl -X GET "http://localhost:8080/api/contacts?page=1&limit=50"
# Search for contacts
curl -X GET "http://localhost:8080/api/contacts?q=alice"
# Get second page with custom limit
curl -X GET "http://localhost:8080/api/contacts?page=2&limit=25"
Go
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
const ApiHost = "http://localhost:8080"
type Contact struct {
UserID int `json:"user_id"`
FirstName string `json:"first_name"`
LastName string `json:"last_name"`
MiddleName string `json:"middle_name"`
AutoAddress string `json:"auto_address"`
Description string `json:"description"`
SendingFee float64 `json:"sending_fee"`
BeaconID string `json:"beacon_id"`
}
type Pagination struct {
Page int `json:"page"`
Limit int `json:"limit"`
Total int `json:"total"`
TotalPages int `json:"total_pages"`
}
type ContactsResponse struct {
Contacts []Contact `json:"contacts"`
Pagination Pagination `json:"pagination"`
}
func main() {
params := url.Values{}
params.Add("page", "1")
params.Add("limit", "50")
params.Add("q", "alice")
resp, err := http.Get(fmt.Sprintf("%s/api/contacts?%s", ApiHost, params.Encode()))
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
var result ContactsResponse
if err := json.Unmarshal(body, &result); err != nil {
panic(err)
}
fmt.Printf("Page %d of %d (Total: %d contacts)\n\n",
result.Pagination.Page,
result.Pagination.TotalPages,
result.Pagination.Total)
for _, contact := range result.Contacts {
fmt.Printf("%s %s\n", contact.FirstName, contact.LastName)
fmt.Printf(" Email: %s\n", contact.AutoAddress)
if contact.Description != "" {
fmt.Printf(" Notes: %s\n", contact.Description)
}
fmt.Println()
}
}