Contacts

Create a contact

POST /v1/contacts

Create a new contact in your workspace.

Request body

Parameter	Type	Required	Description
`email`	`string`	Yes	Contact email address
`first_name`	`string`	No	First name
`last_name`	`string`	No	Last name
`metadata`	`object`	No	Custom key-value data
`tags`	`object`	No	Key-value tags

TypeScript SDK

const contact = await send0.contacts.create({
  email: 'jane@example.com',
  first_name: 'Jane',
  last_name: 'Doe',
  metadata: { plan: 'pro', signup_source: 'landing_page' },
  tags: { segment: 'enterprise' },
});

Python SDK

contact = client.contacts.create(
    email="jane@example.com",
    first_name="Jane",
    last_name="Doe",
    metadata={"plan": "pro", "signup_source": "landing_page"},
    tags={"segment": "enterprise"},
)

Go SDK

contact, err := client.Contacts.Create(ctx, &send0.CreateContactParams{
    Email:     "jane@example.com",
    FirstName: "Jane",
    LastName:  "Doe",
    Metadata:  map[string]any{"plan": "pro", "signup_source": "landing_page"},
    Tags:      map[string]string{"segment": "enterprise"},
})

curl

curl -X POST https://api.send0.dev/v1/contacts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "metadata": { "plan": "pro" }
  }'

Response (201)

{
  "id": "con_7mKpLvRw9nQx",
  "object": "contact",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "metadata": { "plan": "pro", "signup_source": "landing_page" },
  "tags": { "segment": "enterprise" },
  "created_at": "2026-04-12T10:30:00Z",
  "updated_at": "2026-04-12T10:30:00Z"
}

Get a contact

GET /v1/contacts/:id

Retrieve a single contact by ID.

TypeScript SDK

const contact = await send0.contacts.get('con_7mKpLvRw9nQx');

Python SDK

contact = client.contacts.get("con_7mKpLvRw9nQx")

Go SDK

contact, err := client.Contacts.Get(ctx, "con_7mKpLvRw9nQx")

curl

curl https://api.send0.dev/v1/contacts/con_7mKpLvRw9nQx \
  -H "Authorization: Bearer sk_live_..."

List contacts

GET /v1/contacts

Retrieve a paginated list of contacts.

Query parameters

Parameter	Type	Default	Description
`limit`	`number`	20	Results per page (max 100)
`cursor`	`string`	—	Pagination cursor

TypeScript SDK

const { data, has_more, cursor } = await send0.contacts.list({ limit: 50 });

Python SDK

result = client.contacts.list(limit=50)
for contact in result.data:
    print(contact.id, contact.email)

Go SDK

list, err := client.Contacts.List(ctx, &send0.ListContactsParams{
    Limit: 50,
})
for _, contact := range list.Data {
    fmt.Println(contact.ID, contact.Email)
}

curl

curl "https://api.send0.dev/v1/contacts?limit=50" \
  -H "Authorization: Bearer sk_live_..."

Response (200)

{
  "data": [...],
  "has_more": true,
  "cursor": "cur_abc123"
}

Update a contact

PATCH /v1/contacts/:id

Update an existing contact. All fields are optional -- only include the fields you want to change.

TypeScript SDK

const contact = await send0.contacts.update('con_7mKpLvRw9nQx', {
  first_name: 'Janet',
  metadata: { plan: 'enterprise' },
});

Python SDK

contact = client.contacts.update(
    "con_7mKpLvRw9nQx",
    first_name="Janet",
    metadata={"plan": "enterprise"},
)

Go SDK

contact, err := client.Contacts.Update(ctx, "con_7mKpLvRw9nQx", &send0.UpdateContactParams{
    FirstName: send0.String("Janet"),
    Metadata:  map[string]any{"plan": "enterprise"},
})

curl

curl -X PATCH https://api.send0.dev/v1/contacts/con_7mKpLvRw9nQx \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Janet" }'

Delete a contact

DELETE /v1/contacts/:id

Permanently delete a contact.

TypeScript SDK

await send0.contacts.delete('con_7mKpLvRw9nQx');

Python SDK

client.contacts.delete("con_7mKpLvRw9nQx")

Go SDK

err := client.Contacts.Delete(ctx, "con_7mKpLvRw9nQx")

curl

curl -X DELETE https://api.send0.dev/v1/contacts/con_7mKpLvRw9nQx \
  -H "Authorization: Bearer sk_live_..."

Batch upsert contacts

POST /v1/contacts/batch

Create or update multiple contacts at once. Contacts are upserted by email address -- if a contact with the given email already exists, it will be updated.

TypeScript SDK

const result = await send0.contacts.batchUpsert({
  contacts: [
    { email: 'jane@example.com', first_name: 'Jane' },
    { email: 'john@example.com', first_name: 'John', tags: { segment: 'vip' } },
  ],
});

console.log(result.created); // 1
console.log(result.updated); // 1

Python SDK

result = client.contacts.batch_upsert(contacts=[
    {"email": "jane@example.com", "first_name": "Jane"},
    {"email": "john@example.com", "first_name": "John", "tags": {"segment": "vip"}},
])
print(result.created)  # 1
print(result.updated)  # 1

Go SDK

result, err := client.Contacts.BatchUpsert(ctx, &send0.BatchUpsertParams{
    Contacts: []send0.ContactInput{
        {Email: "jane@example.com", FirstName: "Jane"},
        {Email: "john@example.com", FirstName: "John", Tags: map[string]string{"segment": "vip"}},
    },
})
fmt.Println(result.Created) // 1
fmt.Println(result.Updated) // 1

curl

curl -X POST https://api.send0.dev/v1/contacts/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "email": "jane@example.com", "first_name": "Jane" },
      { "email": "john@example.com", "first_name": "John" }
    ]
  }'

Response (200)

{
  "created": 1,
  "updated": 1
}

On this page