List Contacts

Retrieve a list of all contacts in your workspace. Requires full permission.

GET/contacts

Query Parameters

pageinteger

Page number for pagination (minimum: 1, default: 1).

limitinteger

Number of contacts to return (minimum: 1, maximum: 100, default: 10).

GET /contacts

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contacts = await emailit.contacts.list();

from emailit import EmailitClient
client = EmailitClient("your_api_key")

contacts = client.contacts.list()

$emailit = Emailit::client('your_api_key');

$contacts = $emailit->contacts()->list();

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contacts = client.contacts.list

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contacts, err := client.Contacts.List(nil)

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let contacts = emailit.contacts.list(None).await?;

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contacts = emailit.contacts().list();

using Emailit;

var emailit = new EmailitClient("your_api_key");

var contacts = emailit.Contacts.List();

use Emailit\Laravel\Facades\Emailit;

$contacts = Emailit::contacts()->list();

curl https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer your_api_key"

{
  "data": [
    {
      "object": "contact",
      "id": "con_2BxFg7KNqr5M...",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "custom_fields": { "company": "Acme" },
      "unsubscribed": false,
      "audiences": [
        {
          "id": "aud_xxx",
          "name": "Newsletter",
          "subscribed": true
        }
      ],
      "created_at": "2026-02-10T10:00:00.000000+00:00",
      "updated_at": "2026-02-10T10:00:00.000000+00:00"
    }
  ],
  "next_page_url": "/v2/contacts?page=2&limit=10",
  "previous_page_url": null
}

{
  "error": {
    "code": 401,
    "message": "Unauthorized"
  }
}

Get Contact

Retrieve information about a specific contact. Requires full permission. Contacts can be identified by ID (con_xxx) or email address.

GET/contacts/{id}

Path Parameters

idstringRequired

The contact ID (con_xxx) or email address.

Note: The audiences array in the Get endpoint includes full subscriber details (with subscribed_at, unsubscribed_at, etc.), while the List endpoint only includes id, name, and subscribed per audience.

GET /contacts/{id}

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.get('ct_123');

from emailit import EmailitClient
client = EmailitClient("your_api_key")

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

$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->get('ct_123');

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

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

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

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

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.get("ct_123").await?;

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().get("ct_123");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Get("ct_123");

use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->get('ct_123');

curl https://api.emailit.com/v2/contacts/ct_123 \
  -H "Authorization: Bearer your_api_key"

{
  "object": "contact",
  "id": "con_2BxFg7KNqr5M...",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "custom_fields": { "company": "Acme" },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_xxx",
      "name": "Newsletter",
      "subscriber": {
        "id": "sub_xxx",
        "subscribed": true,
        "subscribed_at": "2026-02-10T10:00:00.000000+00:00",
        "unsubscribed_at": null,
        "created_at": "2026-02-10T10:00:00.000000+00:00",
        "updated_at": "2026-02-10T10:00:00.000000+00:00"
      }
    }
  ],
  "created_at": "2026-02-10T10:00:00.000000+00:00",
  "updated_at": "2026-02-10T10:00:00.000000+00:00"
}

{
  "error": "Contact not found"
}

Create Contact

Create a new contact in your workspace. Requires full permission.

POST/contacts

Request Body

emailstringRequired

Email address (must be valid).

first_namestring

First name (default: null).

last_namestring

Last name (default: null).

custom_fieldsobject

Arbitrary key-value pairs (default: null).

audiencesstring[]

Array of audience IDs to subscribe to (default: empty array).

unsubscribedboolean

Global unsubscribe status (default: false).

POST /contacts

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.create({
  email: 'user@example.com',
  first_name: 'John',
  last_name: 'Doe',
});

from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.create({
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
})

$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->create([
  'email' => 'user@example.com',
  'first_name' => 'John',
  'last_name' => 'Doe',
]);

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.create(
  email: "user@example.com",
  first_name: "John",
  last_name: "Doe"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Create(&emailit.CreateContactRequest{
  Email:     "user@example.com",
  FirstName: "John",
  LastName:  "Doe",
})

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.create(
  emailit::types::CreateContactParams::new("user@example.com")
    .with_first_name("John")
    .with_last_name("Doe")
).await?;

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().create(
  ContactCreateParams.builder()
    .setEmail("user@example.com")
    .setFirstName("John")
    .setLastName("Doe")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Create(new ContactCreateOptions {
  Email = "user@example.com",
  FirstName = "John",
  LastName = "Doe",
});

use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->create([
  'email' => 'user@example.com',
  'first_name' => 'John',
  'last_name' => 'Doe',
]);

curl -X POST https://api.emailit.com/v2/contacts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }'

{
  "object": "contact",
  "id": "con_2BxFg7KNqr5M...",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "custom_fields": { "company": "Acme" },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_xxx",
      "name": "Newsletter",
      "subscriber": {
        "id": "sub_xxx",
        "subscribed": true,
        "subscribed_at": "2026-02-10T10:00:00.000000+00:00",
        "unsubscribed_at": null,
        "created_at": "2026-02-10T10:00:00.000000+00:00",
        "updated_at": "2026-02-10T10:00:00.000000+00:00"
      }
    }
  ],
  "created_at": "2026-02-10T10:00:00.000000+00:00",
  "updated_at": "2026-02-10T10:00:00.000000+00:00"
}

{
  "error": "Contact with this email already exists",
  "existing": {
    "object": "contact",
    "id": "con_...",
    "email": "..."
  }
}

Update Contact

Update an existing contact in your workspace. Requires full permission. Contacts can be identified by ID (con_xxx) or email address.

POST/contacts/{id}

Path Parameters

idstringRequired

The contact ID (con_xxx) or email address.

Request Body

emailstring

New email address.

first_namestring

New first name.

last_namestring

New last name.

custom_fieldsobject

Replace custom fields.

unsubscribedboolean

Global unsubscribe status.

PATCH /contacts/{id}

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const contact = await emailit.contacts.update('ct_123', {
  first_name: 'Jane',
});

from emailit import EmailitClient
client = EmailitClient("your_api_key")

contact = client.contacts.update("ct_123", {
  "first_name": "Jane",
})

$emailit = Emailit::client('your_api_key');

$contact = $emailit->contacts()->update('ct_123', [
  'first_name' => 'Jane',
]);

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

contact = client.contacts.update("ct_123", first_name: "Jane")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

contact, err := client.Contacts.Update("ct_123", &emailit.UpdateContactRequest{
  FirstName: "Jane",
})

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let contact = emailit.contacts.update("ct_123",
  emailit::types::UpdateContactParams {
    first_name: Some("Jane".into()),
    ..Default::default()
  }
).await?;

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject contact = emailit.contacts().update("ct_123",
  ContactUpdateParams.builder()
    .setFirstName("Jane")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var contact = emailit.Contacts.Update("ct_123", new ContactUpdateOptions {
  FirstName = "Jane",
});

use Emailit\Laravel\Facades\Emailit;

$contact = Emailit::contacts()->update('ct_123', [
  'first_name' => 'Jane',
]);

curl -X PATCH https://api.emailit.com/v2/contacts/ct_123 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane"}'

{
  "object": "contact",
  "id": "con_2BxFg7KNqr5M...",
  "email": "john@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "custom_fields": { "company": "NewCorp" },
  "unsubscribed": false,
  "audiences": [
    {
      "id": "aud_xxx",
      "name": "Newsletter",
      "subscriber": {
        "id": "sub_xxx",
        "subscribed": true,
        "subscribed_at": "2026-02-10T10:00:00.000000+00:00",
        "unsubscribed_at": null,
        "created_at": "2026-02-10T10:00:00.000000+00:00",
        "updated_at": "2026-02-10T10:00:00.000000+00:00"
      }
    }
  ],
  "created_at": "2026-02-10T10:00:00.000000+00:00",
  "updated_at": "2026-02-12T09:00:00.000000+00:00"
}

{
  "error": "Contact not found"
}

{
  "error": "Contact with this email already exists",
  "existing": {
    "object": "contact",
    "id": "con_...",
    "email": "..."
  }
}

Delete Contact

Delete a contact from your workspace. Requires full permission. This deletes the contact and all associated subscriber records. Fires subscriber.deleted for each subscriber before deletion, then contact.deleted. Contacts can be identified by ID (con_xxx) or email address.

DELETE/contacts/{id}

Path Parameters

idstringRequired

The contact ID (con_xxx) or email address.

DELETE /contacts/{id}

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.contacts.delete('ct_123');

from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.contacts.delete("ct_123")

$emailit = Emailit::client('your_api_key');

$emailit->contacts()->delete('ct_123');

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.contacts.delete("ct_123")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Contacts.Delete("ct_123")

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

emailit.contacts.delete("ct_123").await?;

import com.emailit.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.contacts().delete("ct_123");

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.Contacts.Delete("ct_123");

use Emailit\Laravel\Facades\Emailit;

Emailit::contacts()->delete('ct_123');

curl -X DELETE https://api.emailit.com/v2/contacts/ct_123 \
  -H "Authorization: Bearer your_api_key"

{
  "object": "contact",
  "id": "con_2BxFg7KNqr5M...",
  "email": "john@example.com",
  "deleted": true
}

{
  "error": "Contact not found"
}