Contacts API
Manage your contact list — create, list, update, and suppress contacts.
GET /v1/contacts
List all contacts with pagination and filtering.
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Results per page (max 100) |
offset | integer | 0 | Offset for pagination |
tag | string | - | Filter contacts by tag |
suppressed | boolean | - | Filter by suppression status |
cURL
curl https://api.yoursend.dev/v1/contacts?limit=20&tag=vip \
-H "Authorization: Bearer ys_live_..."
Response
{
"contacts": [
{
"id": "con_abc123",
"email": "user@example.com",
"phone": "+14155551234",
"name": "Jane Doe",
"tags": ["vip", "beta"],
"suppressed": false,
"metadata": { "plan": "pro" },
"created_at": "2025-01-01T00:00:00Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}GET /v1/contacts/:id
Get a single contact by ID.
cURL
curl https://api.yoursend.dev/v1/contacts/con_abc123 \
-H "Authorization: Bearer ys_live_..."
POST /v1/contacts
Create a new contact. Either email or phone is required.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | * | Email address (* either email or phone required) |
phone | string | * | Phone number in E.164 format |
name | string | No | Display name |
tags | string[] | No | Array of tags |
metadata | object | No | Custom key-value metadata |
source | string | No | Source of the contact (default: "api") |
cURL
curl -X POST https://api.yoursend.dev/v1/contacts \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com",
"phone": "+14155551234",
"name": "Jane Doe",
"tags": ["vip"],
"metadata": { "plan": "pro" }
}'
PUT /v1/contacts/:id
Update an existing contact. Pass only the fields you want to change.
| Field | Description |
|---|---|
email, phone, name | Update contact info |
tags, metadata | Update tags or metadata |
email_ok, sms_ok, whatsapp_ok, voice_ok | Channel opt-in preferences |
suppressed | Set to true to suppress the contact from future sends |
suppressed_reason | Reason for suppression (e.g. "unsubscribed", "bounced") |
cURL
curl -X PUT https://api.yoursend.dev/v1/contacts/con_abc123 \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{ "tags": ["vip", "enterprise"], "suppressed": false }'