Contacts API

This API is designed to be simple and easy to use, and is used to manage contacts in your Maileroo account. You can use this API to add, update, and delete contacts, as well as retrieve contact details and manage contact lists.

Authentication

All requests must be authenticated using an organization API key. You can find your API key in the Settings section of the organization dashboard.

To authenticate a request, you must include your sending key in the X-API-Key header of the request. For example: X-API-Key: YOUR_API_KEY.

List ID

The list ID is a unique identifier for a contact list in your Maileroo account. You can find your list ID in the Contacts section of the organization dashboard.

Endpoints

The Contacts API has the following endpoints:

1. Add Contact

You can add a new contact to your account by sending a PUT request to the API endpoint. Your request must include the contact's email address and any additional fields you want to include.

Endpoint: https://manage.maileroo.app/v1/contact/[:list_id]

Method: PUT

Content Type: application/json

Request

The request body should contain a JSON object representing the contact you want to add. The contact object should include the contact's email address and any additional fields you want to include.

Response

The response will be a JSON object containing the following fields:

Field	Description
success	Boolean indicating whether the request was successful
message	Message describing the result of the request

2. Update Contact

You can update an existing contact in your account by sending a PATCH request to the API endpoint. Your request must include the contact's email address and any additional fields you want to update.

Endpoint: https://manage.maileroo.app/v1/contact/[:list_id]/[:email_address]

Method: PATCH

Content Type: application/json

Request

The request body should contain a JSON object representing the contact you want to update. The contact object should include the contact's email address and any additional fields you want to update.

Response

The response will be a JSON object containing the following fields:

Field	Description
success	Boolean indicating whether the request was successful
message	Message describing the result of the request

3. Delete Contact

You can delete an existing contact from your account by sending a DELETE request to the API endpoint. Your request must include the contact's email address.

Endpoint: https://manage.maileroo.app/v1/contact/[:list_id]/[:email_address]

Method: DELETE

Content Type: application/json

Response

The response will be a JSON object containing the following fields:

Field	Description
success	Boolean indicating whether the request was successful
message	Message describing the result of the request

4. Get Contact

You can retrieve the details of an existing contact in your account by sending a GET request to the API endpoint. Your request must include the contact's email address.

Endpoint: https://manage.maileroo.app/v1/contact/[:list_id]/[:email_address]

Method: GET

Content Type: application/json

Response

The response will be a JSON object representing the contact you requested. The contact object will include the contact's email address and any additional fields you have included.

Field	Description
success	Boolean indicating whether the request was successful
message	Message describing the result of the request
contact	Object representing the contact

5. List Contacts

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

Endpoint: https://manage.maileroo.app/v1/contacts/[:list_id]?query=[:query]&page=[:page]

Method: GET

Content Type: application/json

Response

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

Field	Description
success	Boolean indicating whether the request was successful
message	Message describing the result of the request
data	Array that includes information about the contacts

The data field will contain an array that contains current_page, total_pages, total_items, and contacts fields. The contacts field will contain an array of objects representing the contacts.

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

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	Description	Mandatory
subscriber_name	Name of the contact	No
subscriber_email	Email address of the contact	Yes
subscriber_timezone	Timezone of the contact (such as "America/New_York")	No
subscriber_tags	Tags associated with the contact, separated by commas	No
subscriber_status	Status of the contact (such as "SUBSCRIBED", "UNSUBSCRIBED", "UNCONFIRMED", "BOUNCED")	No

In addition to that, 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.

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.

For example:

{
    "subscriber_name": "John Doe",
    "subscriber_email": "john.doe@example.com",
    "subscriber_timezone": "America/New_York",
    "subscriber_tags": "tag1,tag2",
    "subscriber_status": "UNCONFIRMED",
    "custom_field1": "value1",
    "custom_field2": "value2"
}