List contacts

GET/api/v1/contacts

Requires anorganization API keywith the scopecontacts:read

Your contacts, newest first.

For a sync, use since_last_changed. It answers the only question an integration keeping its own copy actually has — what moved — and turns a nightly full-list crawl into a request that usually returns nothing. The value is an ISO 8601 timestamp; remember to URL-encode it, because the + in +00:00 means a space in a query string.

A since_last_changed we cannot parse is IGNORED and you get everything, rather than nothing. The two failures are not symmetrical: a sync handed zero rows concludes it is up to date and stops, and silently misses every change from then on.

Filter on state, not status. status is what the contact row says; state is what the product will actually do, and reconciles that row against your organization's suppression list. A contact whose row says subscribed but whose address you suppressed answers state: "suppressed" and will never be mailed, even though ?status=subscribed returns it.

Parameters

Name	In	Type	Description
`since_last_changed`	query	string	ISO 8601. Returns only contacts modified strictly after this moment. URL-encode it.
`state`	query	string	One of `subscribed`, `unsubscribed`, `bounced`, `complained`, `suppressed`. What the product will do, suppression list included.
`status`	query	string	The stored row value. Kept because it is published; prefer `state`.
`search`	query	string	Matches email or name.
`list_id`	query	string	Only contacts on this list.
`field`	query	string	Filter by one custom field, by its key from `GET /contact-fields`, like `country`. Use with `field_op` and `field_value`: `?field=country&field_value=nigeria`.
`field_op`	query	string	How `field` is matched: `contains` (the default), `equals`, `is_set` (has any value) or `is_not_set` (empty). Case does not matter, the same as in a segment.
`field_value`	query	string	What `field` is compared with. Not needed for `is_set` and `is_not_set`.
`tag`	query	string	Only contacts carrying this tag, matched by NAME and case-insensitively — tags are written by name everywhere, never by id.
`interest_id`	query	string	Only contacts who chose this interest, matched by ID. An interest's name is form copy; rewording it must not change who matches.
`email_status`	query	string	Filter by address check: one value or a comma list of `valid`, `risky`, `invalid`, `unknown`, `pending`, `not_checked` and `never_checked`. `never_checked` means from before Bounce protection launched; for everything not checked yet, use `not_checked,never_checked`. `inbox_full` selects contacts on a full-inbox hold (they also read `risky`).
`created_via`	query	string	Filter by how the contact was added: one value or a comma list of `dashboard`, `api` (POST /contacts), `upsert` (PUT /contacts), `import` and `event`. `api,upsert` means added by your app.
`per_page`	query	integer	Page size.

Request

GET/api/v1/contacts

curl -X GET 'https://app.mailyte.com/api/v1/contacts' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

const response = await fetch('https://app.mailyte.com/api/v1/contacts', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
  },
});
const { data } = await response.json();

import requests
response = requests.get(
    "https://app.mailyte.com/api/v1/contacts",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->get('https://app.mailyte.com/api/v1/contacts');

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/contacts")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

The key names its own organization, so no X-Organization-ID header is needed.

Response

Success.

dataobject
- dataarray<object>
  - objectstringcontact
  - idstring
    Unique identifier for the contact.
  - emailstring
    Lower-cased and trimmed on write, so the address you read back may not be byte-identical to the one you sent.
  - namestring
    The contact's name. Null when none was given; {{ name }} is then empty unless your template gives a fallback.
  - statestringsubscribed | unsubscribed | bounced | complained | suppressed
    Whether this contact will be emailed. subscribed means yes; any other value is the reason not. It combines the contact's status with your suppression list, so a subscribed contact whose address is suppressed reads suppressed. Read-only: you set status (subscribed, unsubscribed, bounced or complained) instead. Note that ?status= filters on status, not on this.
  - email_statusstringpending | valid | risky | invalid | unknown | not_checked
    The result of checking whether the mailbox exists. valid: it exists. invalid: it does not. risky: it may not take mail (a catch-all domain, a role address such as info@, a throwaway address or a full inbox). unknown: the check could not tell. pending: being checked. not_checked: added after Bounce protection launched and not checked. Null: never checked, from before Bounce protection launched. Read-only; filter with ?email_status=.
  - email_full_untilstring
    Until when marketing to this contact is held because their inbox is full. When a check finds the inbox full, marketing waits 7 days; near the end it is checked again for free and the hold either ends or runs another 7 days. App email is never held. Null means no hold. Read-only.
  - fieldsobject
    Custom field values, keyed by the field's key (the name {{ signup_date }} uses). Always an object, {} when empty. Values are strings as stored; field defaults are not filled in here. When writing, send these as attributes.
  - listsarray<object>
    The lists this contact is on, with their names. When writing, send list IDs as list_ids.
    - idstring
    - namestring
  - tagsarray<object>
    Your labels on this contact, with their names.
    - idstring
    - namestring
  - interestsarray<object>
    What this contact chose on a form, each with the question it answers. [] means they chose nothing.
    - idstring
      Match on this in a segment rule, never on the name.
    - namestring
      The answer, as the contact read it.
    - category_idstring
      The question this answers.
    - category_titlestring
      The question in words. null MEANS NOT INCLUDED — the category was not loaded, never that the question has no title.
  - consentobject
    How this contact agreed to be emailed. Each field is null when we have no record. Set it when you import from another service, so your proof of consent comes with your contacts.
    - atstring
      When they agreed. Null when unknown.
    - ipstring
      The IP address they agreed from. Null when unknown.
    - sourcestring
      Where they agreed, such as a form name, a URL or "imported from Mailchimp". Null when unknown.
  - sourcestring
    How this contact was added: manual, import_api, import_csv or your own text (up to 50 characters). Null when nothing was recorded.
  - created_atstring
  - updated_atstring
- pagination_metaany

Returned inside the standard envelope.

Errors

Status	When
`401`	The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
`403`	The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
`404`	No such resource in this organization.
`422`	The request was understood but the values were not acceptable.
`429`	Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.