List Contacts

You can retrieve a list of contacts in your account by sending a GET request to the API endpoint.

Endpoint Information

Endpoint: https://manage.maileroo.app/v1/contacts/[:list_id]?query=[:query]&page=[:page]
Method: GET
Content Type: application/json
Authentication: Required

Where To Find Your List ID

You can find your list ID in your when you to go to your 'Contacts' section within your organization. There it will display the list-id that you can use in this endpoint.

Request

The GET request does not require a request body. All necessary information is provided in the URL parameters.

Request Headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY_HERE

URL Parameters

Parameter	Type	Description	Required
list_id	string	The ID of the list to retrieve contacts from	Yes
query	string	Search query to filter contacts (optional)	No
page	integer	Page number for pagination (default: 1)	No

Search Functionality

The query parameter allows you to search for contacts by name, email, or tags. This is useful for finding specific contacts in large lists.

Pagination

Use the page parameter to navigate through large lists of contacts. Each page typically contains a limited number of contacts for optimal performance.

Response

The response will be a JSON object representing the list of contacts you requested. The response object will include the following fields:

Field	Type	Description
success	boolean	Boolean indicating whether the request was successful
message	string	Message describing the result of the request
data	object	Object containing pagination and contact information

Data Object Structure

The data field will contain an object with the following fields:

Field	Type	Description
current_page	integer	Current page number
total_pages	integer	Total number of pages
total_items	integer	Total number of items
contacts	array	Array of objects representing the contacts

Success Response

{
  "success": true,
  "message": "Contacts retrieved successfully",
  "data": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 125,
    "contacts": [
      {
        "subscriber_name": "John Doe",
        "subscriber_email": "[email protected]",
        "subscriber_timezone": "America/New_York",
        "subscriber_tags": "customer,premium",
        "subscriber_status": "SUBSCRIBED",
        "custom_field1": "value1",
        "custom_field2": "value2"
      },
      {
        "subscriber_name": "Jane Smith",
        "subscriber_email": "[email protected]",
        "subscriber_timezone": "Europe/London",
        "subscriber_tags": "prospect",
        "subscriber_status": "UNCONFIRMED",
        "custom_field1": "value3"
      }
    ]
  }
}

Error Response

{
  "success": false,
  "message": "List not found"
}

Contact Object

A contact object represents a contact in your Maileroo account. It contains information about the contact, such as their name, email address, and status. It is represented as a JSON object with the following fields:

Field	Type	Description	Mandatory
subscriber_name	string	Name of the contact	No
subscriber_email	string	Email address of the contact	Yes
subscriber_timezone	string	Timezone of the contact (such as "America/New_York")	No
subscriber_tags	string	Tags associated with the contact, separated by commas	No
subscriber_status	string	Status of the contact	No

Contact Status Values

Status	Description
SUBSCRIBED	Contact is actively subscribed and can receive emails
UNSUBSCRIBED	Contact has unsubscribed from emails
UNCONFIRMED	Contact has not confirmed their subscription
BOUNCED	Contact's email address has bounced

Confirmation Emails

If you would like the system to send a confirmation email to the contact, you can use the status "UNCONFIRMED" as this will trigger the system to send a confirmation email to the contact.

Custom Fields

In addition to the standard fields, you can also include custom fields in the contact object. Custom fields are additional fields that you can use to store information about the contact, such as their age, location, or interests. Custom fields are represented as key-value pairs in the contact object, and can be used with templates and for segmentation.

Example Contact Object

{
  "subscriber_name": "John Doe",
  "subscriber_email": "[email protected]",
  "subscriber_timezone": "America/New_York",
  "subscriber_tags": "tag1,tag2",
  "subscriber_status": "UNCONFIRMED",
  "custom_field1": "value1",
  "custom_field2": "value2"
}