Listomo API

Welcome to the Listomo API. You can use our API to access Listomo API endpoints. You can create and edit lists, forms and contacts via the Listomo API.

Current language bindings are in cURL.

Listomo uses API keys to allow access to the API. You can register a new Listomo API key in your api tokens section of your profile.

Listomo expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer my-api-token

Authentication

Get Auth Token

# To obtain an auth token, either use your auth token from your profile, or obtain one via this api. 
curl 'https://api.listomo.com/v1/auth' \
-H 'Content-Type: application/json' \
-d '{
    "email": "[email protected]",
    "password": "super-secret-password"
}'

{
    "token": "secretsquirrel"
}

Gets an auth token from the server to use for subsequent requests. You can also get your own auth token (api key) manually here.

HTTP Request

POST http://api.listomo.com/v1/auth

Body Parameters

Parameter	Type	Description	Required
email	string	The email to your account	✅
password	string	Your password	✅

Accounts

Get All Accounts

curl -L 'https://api.listomo.com/v1/accounts' \
-H 'Authorization: Bearer secretsquirrel' \

[
    {
        "id": 4,
        "name": "Your List Name",
        "personal": true,
        "owner_id": 4,
        "created_at": "2023-08-19T11:52:01.211-04:00",
        "updated_at": "2023-08-19T11:52:01.211-04:00",
        "account_users": [
            {
                "id": 4,
                "user_id": 4
            }
        ]
    }
]

This endpoint retrieves all accounts associated with the current user.

HTTP Request

GET http://api.listomo.com/v1/accounts

Lists

All the email lists in your account. Each account can have multiple lists. You might have a list for Product A, and another one for Product B, etc.

Get all lists for account

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/' \
-H 'Authorization: Bearer secretsquirrel'

[
    {
        "id": 1,
        "key": "FzuQXgykYQ5REuSyBU49W9wR",
        "name": "Goldner - Swaniawski",
        "description": "Aperiam eius recusandae fugiat quia commodi totam.",
        "open_tracking_enabled": true,
        "block_free_email_providers": true,
        "block_disposable_email_providers": true,
        "list_unsubscribe_url": "http://app.listomo.com/lists/FzuQXgykYQ5REuSyBU49W9wR/unsubscribe",
        "created_at": "2023-08-19T15:57:07Z",
        "updated_at": "2023-08-19T17:14:43Z",
        "mail_provider": "sendgrid"
    },
    {
        "id": 2,
        "key": "oBNme1FqNGGzebcgDHCgq82X",
        "name": "Grant Group",
        "description": "Atque explicabo sit.",
        "open_tracking_enabled": true,
        "block_free_email_providers": false,
        "block_disposable_email_providers": true,
        "list_unsubscribe_url": "http://app.listomo.com/lists/oBNme1FqNGGzebcgDHCgq82X/unsubscribe",
        "created_at": "2023-08-19T17:14:17Z",
        "updated_at": "2023-08-19T17:14:17Z",
        "mail_provider": "sendgrid"
    }
]

This endpoint retrieves all the lists for the account.

HTTP Request

GET http://api.listomo.com/v1/accounts/:account_id/lists/

URL Parameters

Parameter	Description
account_id	The ID of the account

Get List

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id' \
-H 'Authorization: Bearer secretsquirrel' \

{
    "id": 1,
    "key": "FzuQXgykYQ5REuSyBU49W9wR",
    "name": "Goldner - Swaniawski",
    "description": "Aperiam eius recusandae fugiat quia commodi totam.",
    "open_tracking_enabled": true,
    "block_free_email_providers": true,
    "block_disposable_email_providers": true,
    "list_unsubscribe_url": "http://app.listomo.com/lists/FzuQXgykYQ5REuSyBU49W9wR/unsubscribe",
    "created_at": "2023-08-19T15:57:07Z",
    "updated_at": "2023-08-19T17:14:43Z",
    "mail_provider": "sendgrid"
}

This endpoint retrieves the specific list as per the list_id param

HTTP Request

GET http://api.listomo.com/v1/accounts/:account_id/lists/:list_id

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list

Create a List

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{
    "list" : {
        "name": "Bobs Fitness",
        "description": "A list for Bobs fitness."
    }
}'

{
    "id": 7,
    "key": "XY787CK9r2KPrG1r5wwzMXJy",
    "name": "Bobs Fitness",
    "description": "A list for Bobs fitness.",
    "open_tracking_enabled": true,
    "block_free_email_providers": false,
    "block_disposable_email_providers": true,
    "list_unsubscribe_url": "https://app.listomo.com/lists/XY787CK9r2KPrG1r5wwzMXJy/unsubscribe",
    "created_at": "2023-08-20T21:43:17Z",
    "updated_at": "2023-08-20T21:43:17Z",
    "mail_provider": "sendgrid"
}

HTTP Request

POST https://api.listomo.com/v1/accounts/:account_id/lists/

URL Parameters

Parameter	Description
account_id	The ID of the account

Body Parameters

Parameter	Type	Description	Required
name	string	The name of the list	✅
description	string	the description of the list	✅
open_tracking_enabled	boolean	If open tracking is enabled on this list. If off, pixel tracking is disabled and you won't be able to know if the contact opened a message.
block_free_email_providers	boolean	default: false - Block over 3,900 free email providers (Gmail, Yahoo, etc) from joining this list
block_disposable_email_providers	boolean	default: true - Block over 161,000 disposable/throw-away email providers (recommended, it improves your list health)

This endpoint allows you to create a list.

Update a List

curl -L -X PATCH 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{
    "list" : {
        "name": "Too Legit to Quit",
        "description": "Ok Stop, Hammer Time",
        "open_tracking_enabled": true,
        "block_free_email_providers": true,
        "block_disposable_email_providers": true
    }
}'

{
    "id": 1,
    "key": "FzuQXgykYQ5REuSyBU49W9wR",
    "name": "Too Legit to Quit",
    "description": "Ok Stop, Hammer Time",
    "open_tracking_enabled": true,
    "block_free_email_providers": true,
    "block_disposable_email_providers": true,
    "list_unsubscribe_url": "http://app.listomo.com/lists/FzuQXgykYQ5REuSyBU49W9wR/unsubscribe",
    "created_at": "2023-08-19T15:57:07Z",
    "updated_at": "2023-08-20T22:10:11Z",
    "mail_provider": "sendgrid"
}

HTTP Request

PATCH http://api.listomo.com/v1/accounts/:account_id/lists/:list_id

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list

Body Parameters

Parameter	Type	Description
name	string	The name of the list
description	string	the description of the list
open_tracking_enabled	boolean	If open tracking is enabled on this list. If off, pixel tracking is disabled and you won't be able to know if the contact opened a message.
block_free_email_providers	boolean	default: false - Block over 3,900 free email providers (Gmail, Yahoo, etc) from joining this list
block_disposable_email_providers	boolean	default: true - Block over 161,000 disposable/throw-away email providers (recommended, it improves your list health)

This endpoint allows you to update a list. A list must have a name at all times.

Delete a List

curl -L -X DELETE 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d ''

HTTP Request

DELETE http://api.listomo.com/v1/accounts/:account_id/lists/:list_id

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list to delete

This endpoint deletes a specific list.

Forms

Forms are how your contacts are added to your list. Each list is has a default form that is created when the list is created. You can create other forms to help track the origin of your contacts. For example, you might have a form for your contacts that you collect on your sale page, another one that collects leads from your personal site/Instagram/TikTok/X page, etc.

Forms have double confirmation emails attached to them. When a contact first joins your list (or re-joins after an unsubscribe), the first form that they subscribe to will send them a double confirmation email. The email contents are editable in your Listomo dashboard.

List All Forms

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms' \
-H 'Authorization: Bearer secretsquirrel' \

[
    {
        "id": 1,
        "list_id": 1,
        "key": "H7e18ZPWTnySJGR1Gg3dBhREgxYDuwon",
        "name": "Default Hosted Form",
        "thank_you_url": null,
        "success_message": null,
        "hosted_form_url": "http://app.listomo.com/forms/H7e18ZPWTnySJGR1Gg3dBhREgxYDuwon/subscribe",
        "created_at": "2023-08-19T15:57:07Z",
        "updated_at": "2023-08-19T15:57:07Z"
    },
    {
        "id": 3,
        "list_id": 1,
        "key": "hoYfZv1BZCj8FJn6y66RNucAefGbtmz3",
        "name": "My Favorite Form",
        "thank_you_url": "http://harry.net",
        "success_message": "Self-enabling human-resource synergy",
        "hosted_form_url": "http://app.listomo.com/forms/hoYfZv1BZCj8FJn6y66RNucAefGbtmz3/subscribe",
        "created_at": "2023-08-20T23:16:25Z",
        "updated_at": "2023-08-20T23:16:25Z"
    }
]

Returns all the forms associated with the list via the :list_id.

HTTP Request

GET http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list

Get Form

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms/:form_id' \
-H 'Authorization: Bearer secretsquirrel'

{
    "id": 1,
    "list_id": 1,
    "key": "H7e18ZPWTnySJGR1Gg3dBhREgxYDuwon",
    "name": "Default Hosted Form",
    "thank_you_url": null,
    "success_message": null,
    "hosted_form_url": "http://app.listomo.com/forms/H7e18ZPWTnySJGR1Gg3dBhREgxYDuwon/subscribe",
    "created_at": "2023-08-19T15:57:07Z",
    "updated_at": "2023-08-19T15:57:07Z"
}

Gets the specified form.

If the thank_you_url is null, the system default will be used. If the success_message is null, the system default will be used.

HTTP Request

GET http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms/:form_id

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list
form_id	The ID of the form

Create Form

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{
    "form" : {
        "name": "Parker, Schuster and Lang Form",
        "thank_you_url": "http://example.biz/thank-you",
        "success_message": "Object-based bi-directional concept"
    }
}'

{
    "id": 4,
    "list_id": 1,
    "key": "bdGyyzGphEjppkyudQUu27DxvwJ12Mzj",
    "name": "Parker, Schuster and Lang Form",
    "thank_you_url": "http://example.biz/thank-you",
    "success_message": "Object-based bi-directional concept",
    "hosted_form_url": "http://app.listomo.com/forms/bdGyyzGphEjppkyudQUu27DxvwJ12Mzj/subscribe",
    "created_at": "2023-08-20T23:26:55Z",
    "updated_at": "2023-08-20T23:26:55Z"
}

Creates a new form in the list.

HTTP Request

POST http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list

Body Parameters

Parameter	Type	Description	Required
name	string	The name of the form	✅
thank_you_url	string	The url where the contact is redirected to when they successfully subscribe
success_messages	string	The message the contact is shown if the `thank_you_url` is not present

Update a Form

curl -L -X PATCH 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms/:form_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{
    "form" : {
        "name": "Down-sized didactic toolset Form",
        "thank_you_url": "https://claude.org/thank-you",
        "success_message": "Et ut voluptas."
    }
}'

{
    "id": 1,
    "list_id": 1,
    "key": "H7e18ZPWTnySJGR1Gg3dBhREgxYDuwon",
    "name": "Down-sized didactic toolset Form",
    "thank_you_url": "https://claude.org/thank-you",
    "success_message": "Et ut voluptas.",
    "hosted_form_url": "http://app.listomo.com/forms/H7e18ZPWTnySJGR1Gg3dBhREgxYDuwon/subscribe",
    "created_at": "2023-08-19T15:57:07Z",
    "updated_at": "2023-08-20T23:32:23Z"
}

Updates the form.

HTTP Request

POST http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms/:form_id

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list
form_id	The ID of the form to update

Body Parameters

Parameter	Type	Description
name	string	The name of the form
thank_you_url	string	The url where the contact is redirected to when they successfully subscribe
success_messages	string	The message the contact is shown if the `thank_you_url` is not present

Delete a Form

curl -L -X DELETE 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms/:form_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d ''

Deletes a form from the list.

HTTP Request

DELETE http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/forms/:form_id

URL Parameters

Parameter	Description
account_id	The ID of the account
list_id	The ID of the list
form_id	The ID of the form to delete

Contacts

Contacts are the core of your email list. They are who you contact for your broadcasta and campaigns.

A contact can only belong to one list, but can belong to many forms in that list. For example, your contact might have signed up directly to your email list from the default form, but at a later time they might have been interested (and possbily not sure if they were part of your list yet) so they signed up to your sales page form as well. This shows the contact has come to your list for multiple reasons.

In future versions of Listomo, you will be able to perform automations when contacts subscribe to various forms on your list.

List Contacts

curl -L 'http://api.lvh.me:3000/v1/accounts/:account_id/lists/:list_id/contacts' \
-H 'Authorization: Bearer secretsquirrel' \

{
    "contacts": [
        {
            "id": 4849,
            "email": "[email protected]",
            "first_name": "Leroy",
            "last_name": "Jenkins",
            "list_id": 1,
            "notes": "Knows how to charge into battle, he's a great help!",
            "double_opt_in": false,
            "confirmed_at": "2023-08-21T01:07:09Z",
            "created_at": "2023-08-21T01:06:03Z",
            "updated_at": "2023-08-21T01:51:03Z",
            "forms": [
                {
                    "name": "Instagram Leads",
                    "id": 3,
                    "created_at": "2023-08-21T01:51:03Z"
                },
                {
                    "name": "Free E-Book Form",
                    "id": 4,
                    "created_at": "2023-08-21T01:51:56Z"
                }
            ]
        },
        {
            "id": 4848,
            "email": "[email protected]",
            "first_name": "Sonny",
            "last_name": "",
            "list_id": 1,
            "notes": null,
            "double_opt_in": false,
            "confirmed_at": "2023-08-21T01:07:09Z",
            "created_at": "2023-08-21T01:06:03Z",
            "updated_at": "2023-08-21T01:07:09Z",
            "forms": []
        },
        ... 
    ],
    "pagination": {
        "page": 1,
        "pages": 194,
        "count": 4849,
        "items": 25
    }
}

Gets a paginated result of contacts from the API.

HTTP Request

GET http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅
page	The page number

Paged Request Format

GET http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts?page=2

Pagination Value Descriptions

Parameter	Description
page	What page is currently returned
pages	Total number of pages
count	Total number of contacts
items	Number of contacts per page

Get Contact

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id' \
-H 'Authorization: Bearer secretsquirrel' \

{
    "id": 4849,
    "email": "[email protected]",
    "first_name": "Leroy",
    "last_name": "Jenkins",
    "list_id": 1,
    "notes": "Knows how to charge into battle, he's a great help!",
    "double_opt_in": false,
    "confirmed_at": "2023-08-21T01:07:09Z",
    "created_at": "2023-08-21T01:06:03Z",
    "updated_at": "2023-08-21T01:51:03Z",
    "forms": [
        {
            "name": "Instagram Leads",
            "id": 3,
            "created_at": "2023-08-21T01:51:03Z"
        },
        {
            "name": "Free E-Book Form",
            "id": 4,
            "created_at": "2023-08-21T01:51:56Z"
        }
    ]
}

Gets a contact from the list.

HTTP Request

GET http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅
contact_id	The ID of the contact	✅

Create Contact with Double Opt-In

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/' \
-H 'Authorization: Bearer secretsquirrel' \
--data-raw '{
    "contact" : {
        "email": "[email protected]",
        "first_name": "Vern",
        "last_name": "Hauck",
        "form_ids": [
            4
        ]
    }
}'

{
    "id": 4850,
    "email": "[email protected]",
    "first_name": "Vern",
    "last_name": "Hauck",
    "list_id": 1,
    "notes": null,
    "double_opt_in": true,
    "confirmed_at": null,
    "created_at": "2023-08-21T11:56:09Z",
    "updated_at": "2023-08-21T11:56:09Z",
    "forms": [
        {
            "name": "Free E-Book Form",
            "id": 4,
            "created_at": "2023-08-21T11:56:09Z"
        }
    ]
}

Creates a contact and add's them to the form. A form_id value is required, maximum number of 1 value. When adding the contact to the form, the contact will be sent a double opt-in email that is associated with said form.

HTTP Request

POST http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅

Body Parameters

Parameter	Type	Description	Required
email	string	The contacts email	✅
first_name	string	The first name of the contact
last_name	string	The last name of the contact
form_ids	array	The form to add the contact to	✅
notes	string	Notes to add to the contact

Create Contact without Double Opt-In

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/' \
-H 'Authorization: Bearer secretsquirrel' \
--data-raw '{
    "contact" : {
        "email": "[email protected]",
        "first_name": "Leroy",
        "last_name": "Jenkins",
        "double_opt_in": false
    }
}'

{
    "id": 4851,
    "email": "[email protected]",
    "first_name": "Leroy",
    "last_name": "Jenkins",
    "list_id": 1,
    "notes": null,
    "double_opt_in": false,
    "confirmed_at": "2023-08-21T12:14:21Z",
    "created_at": "2023-08-21T12:14:21Z",
    "updated_at": "2023-08-21T12:14:21Z",
    "forms": []
}

Adds a contact to the list, skipping double confirmation by not adding them to a form.

HTTP Request

POST http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅

Body Parameters

Parameter	Type	Description	Required
email	string	The contacts email	✅
first_name	string	The first name of the contact
last_name	string	The last name of the contact
double_opt_in	boolean	Whether to send the contact a double opt in email, if `false`, a form_id is not needed
form_ids	array	Forms to add the contact to
notes	string	notes to add to the contact

Update Contact

curl -L -X PATCH 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{
    "contact" : {
        "first_name": "Abbey",
        "last_name": "Jaskolski",
        "notes": "Quae libero non vel ut nam tenetur ea ut. Aspernatur fugit ut nulla officia nulla qui."   
    }
}'

{
    "id": 4851,
    "email": "[email protected]",
    "first_name": "Abbey",
    "last_name": "Jaskolski",
    "list_id": 1,
    "notes": "Quae libero non vel ut nam tenetur ea ut. Aspernatur fugit ut nulla officia nulla qui.",
    "double_opt_in": false,
    "confirmed_at": "2023-08-21T12:14:21Z",
    "created_at": "2023-08-21T12:14:21Z",
    "updated_at": "2023-08-21T12:22:54Z",
    "forms": []
}

Updates a contact.

HTTP Request

PATCH http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅
contact_id	The ID of the contact	✅

Body Parameters

Parameter	Type	Description	Required
email	string	The contacts email	✅
first_name	string	The first name of the contact
last_name	string	The last name of the contact
notes	boolean	Whether to send the contact a double opt in email, if `false`, a form_id is not needed

Delete Contact

curl -L -X DELETE 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d ''

Deletes a contact from the list.

HTTP Request

DELETE http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅
contact_id	The ID of the contact	✅

Add Form to Contact

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id/forms' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{    
    "form_ids": [
        1,
        3
    ]   
}'

{
    "id": 4849,
    "email": "[email protected]",
    "first_name": "",
    "last_name": "",
    "list_id": 1,
    "notes": "",
    "double_opt_in": false,
    "confirmed_at": "2023-08-21T01:07:09Z",
    "created_at": "2023-08-21T01:06:03Z",
    "updated_at": "2023-08-21T01:51:03Z",
    "forms": [
        {
            "name": "E-Book Form",
            "id": 3,
            "created_at": "2023-08-21T01:51:03Z"
        },
        {
            "name": "Instagram Leads Form",
            "id": 1,
            "created_at": "2023-08-21T12:33:45Z"
        }
    ]
}

Adds a contact to one to many forms.

HTTP Request

POST http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id/forms

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅
contact_id	The ID of the contact	✅

Body Parameters

Parameter	Type	Description	Required
form_ids	array	Forms to add the contact to	✅

Delete form from Contact

curl -L -X DELETE 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id/forms/:form_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d ''

{
    "id": 4849,
    "email": "[email protected]",
    "first_name": "",
    "last_name": "",
    "list_id": 1,
    "notes": "",
    "double_opt_in": false,
    "confirmed_at": "2023-08-21T01:07:09Z",
    "created_at": "2023-08-21T01:06:03Z",
    "updated_at": "2023-08-21T01:51:03Z",
    "forms": [
        {
            "name": "Instagram Leads Form",
            "id": 1,
            "created_at": "2023-08-21T12:33:45Z"
        }
    ]
}

Deletes a form from a contact.

HTTP Request

DELETE http://api.listomo.com/v1/accounts/:account_id/lists/:list_id/contacts/:contact_id/forms/:form_id

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅
contact_id	The ID of the contact	✅
form_id	The ID of the form to delete	✅

Inspect Email Tool

Inspect an email address to determine if it is a valid email address, if it is a disposable email address, and if it is a free email address.

Does not require a paid account, but does require that you have an API key. Sign up and you can get a free API key in the account settings.

This API call is Rate-Limited to 10 calls per minute. Exceeding that rate limit will result in a 429 Too Many Requests response.

Inspect Email

curl -L 'https://api.listomo.com/v1/[email protected]' \
-H 'Authorization: Bearer secretsquirrel'

{
  "domain": "gmail.com",
  "is_free_email": true,
  "is_disposable_email": false,
  "is_valid_tld": true,
  "last_updated_at": "2024-03-14T13:58:53.937-04:00"
}

Gets details about an email address. THis API call will inform you whether or not an email address is a free email address, a disposable email address, and if the TLD is valid.

Free email, disposable emails and TLD records are updated nightly, if any changes are made to the records, the last_updated_at field will be updated.

This API call is Rate-Limited to 10 calls per minute. Exceeding that rate limit will result in a 429 Too Many Requests response.

HTTP Request

GET http://api.listomo.com/v1/inspect-email?email=:email_address

URL Parameters

Parameter	Description	Required
email_address	The email address to check	✅

MCP Server

The MCP (Model Context Protocol) Server allows AI assistants to interact with your Listomo data. This enables seamless integration with tools like Cursor, Claude Code, Claude Desktop, and many more agents to manage your lists, contacts, and forms.

Getting Your API Token

Before connecting to the Listomo MCP server, you'll need an API token:

Log in to your Listomo account
Navigate to https://app.listomo.com/api_tokens
Create a new API token or copy an existing one
Keep this token secure - it provides access to your Listomo account

MCP Server Endpoint

The Listomo MCP server is available at:

https://mcp.listomo.com

To connect to this endpoint, you'll need: 1. Server URL: https://mcp.listomo.com 2. API Token: Required for authentication - get yours at https://app.listomo.com/api_tokens

All MCP clients must include your API token in the Authorization header as a Bearer token when connecting to this endpoint.

Available MCP Tools

Once connected, the following tools are available for interacting with your Listomo data:

Account Management

list_accounts: Get all accounts accessible to your API token

List Management

list_lists: Get all lists for a specified account with comprehensive details
create_list: Create a new email list with custom settings
show_list: Get detailed information about a specific list

Contact Management

list_contacts: Get all contacts for a specified list
create_contact: Create a new contact for an email list with optional double opt-in
show_contact: Get detailed information about a specific contact
search_contacts: Search contacts with comprehensive filters (email, name, status, dates, etc.)

Form Management

list_forms: Get all forms for a specified list
show_form: Get detailed information about a specific form

Email & Broadcast Management

show_email: Get detailed information about a specific email
show_broadcast: Get detailed information about a specific broadcast campaign

Example Usage

"List all my accounts."
"Show me all lists for my account." (if you have one account)
"Show me all lists for my 'Company ABC' account."
"Create a new list called 'Basket Weaving Subscribers' in my account." (or ... 'in my Company ABC account')
"How many subscribers have I gained in the last 30 days in my 'Growth Course' list?"
"How many subscribers have unsubscribed in that same list in the last 60 days?"
"Add [email protected] to list 'Basket Weaving Subscribers'."
"Search for confirmed contacts created in the last 7 days in the 'Basket Weaving Subscribers' list."
"Show details for contact with email [email protected]."
"List all forms for my marketing list."
"Show broadcast details for campaign ID 789."
"What was the last email that [email protected] opened in the 'Basket Weaving Subscribers' list?"

Tool Parameters

Most tools support various parameters for filtering and customization:

Pagination: Use page and items parameters for large result sets
Filtering: Search by email, name, status, date ranges
Limiting: Control the number of results returned with limit parameter
Account Scope: Most tools require an account_id to scope operations

Cursor Configuration

{
  "mcpServers": {
    "Listomo MCP": {
      "url": "https://mcp.listomo.com",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
      }
    }
  }
}

To connect Cursor to Listomo:

Open your project in Cursor
Create or edit the .cursor/config.json file in your project root
Add the MCP server configuration with your API token
Restart Cursor to apply the configuration
The Listomo MCP server will now be available in your Cursor environment

Claude Code Configuration

{
  "mcpServers": {
    "listomo": {
      "url": "https://mcp.listomo.com",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
      }
    }
  }
}

To configure Claude Code with Listomo MCP:

Open Claude Code settings
Navigate to the MCP configuration section
Add the Listomo server configuration
Save and reload Claude Code
You can now use Claude Code to interact with your Listomo data

Claude Desktop Configuration

{
  "servers": {
    "listomo": {
      "url": "https://mcp.listomo.com",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
      },
      "description": "Connect to Listomo API for list and contact management"
    }
  }
}

To set up Claude Desktop with Listomo:

Locate your Claude Desktop configuration directory:
- macOS/Linux: ~/.config/claude/
- Windows: %APPDATA%\claude\
Create or edit the mcp.json file
Add the Listomo server configuration with your API token
Restart Claude Desktop to apply changes
The Listomo MCP integration will be available in your conversations

Webhooks

Receive real time notifications about events happening on your lists with webhooks.

Webhooks are list specific, so you can set up different webhooks for each list. Each list can have multiple webhook endpoints. You can set up webhooks in the list settings of the app or via the API.

Webhook Events

The following webhook events are available:

Event is posted to your webhook endpoint when with ...

{
  "key": "hga6u4z5252csfzjx412bacfwxmudo8pcfhj",
  "id": 349960339,
  "first_name": "Leroy",
  "last_name": "Jenkins",
  "email": "[email protected]",
  "subscribed_at": "2023-09-04T11:55:17Z",
  "unsubscribed_at": null,
  "created_at": "2023-09-01T11:55:17Z",
  "double_opt_in": true,
  "list": {
    "id": 980190962,
    "key": "oBNme1FqNGGzebcgDHCgq82X",
    "name": "Leroy's Gaming Blog"
  }
}

{
    "contact": {
        "key": "hga6u4z5252csfzjx412bacfwxmudo8pcfhj",
        "id": 349960339,
        "first_name": "Leroy",
        "last_name": "Jenkins",
        "email": "[email protected]",
        "subscribed_at": "2023-09-04T10:52:14Z",
        "unsubscribed_at": null,
        "created_at": "2023-09-06T10:52:14Z",
        "double_opt_in": true,
        "list": {
            "id": 980190962,
            "key": "oBNme1FqNGGzebcgDHCgq82X",
            "name": "Leroy's Gaming Blog"
        }
    },
    "form": {
        "id": 419489459,
        "name": "Leroy's Gaming Tips",
        "subscribed_at": "2023-09-06T10:52:14Z"
    },
    "list": {
        "id": 980190962,
        "key": "oBNme1FqNGGzebcgDHCgq82X",
        "name": "Leroy's Gaming Blog"
    }
}

{
    "id": 419489459,
    "name": "Leroy's Gaming Tips",
    "created_at": "2023-09-06T11:20:58Z",
    "list": {
        "id": 980190962,
        "name": "Leroy's Gaming Blog", 
        "key": "oBNme1FqNGGzebcgDHCgq82X"
    }
}

contact.subscribed - A contact has subscribed to a list
contact.unsubscribed - A contact has unsubscribed from a list
contact.form_subscribed - A contact has subscribed to a particular form on a list
form.created - A form has been created on a list

Webhook Retries

If Listomo cannot reach your webhook endpoint to deliver a particular event, it will retry sending the webhook event for up to 3 days at increasing intervals. After that point the event will be abandoned and will not be retried. In the webhook settings of Listomo you can see the events that have been abandoned and the response and response code that was returned by your webhook endpoint.

Webhook Errors

Listomo will retry most errors, except for DNS errors. In order to save bandwidth Listomo will disable any endpoint that experiences DNS issues until you resolve it. You can re-enable it in the Listomo app.

Using ngrok

Many developers will use tunnelling services like ngrok.io to test their webhooks. If you are using ngrok, you will receive your webhooks when the tunnel is active. However, if we cannot reach your tunnel, we will disable the webhook if we receive a 504 result form ngrok. This error code typically means that your stable tunnel is not active. If we receive a 404 result form ngrok we will delete the tunnel as it is not active and most likely a temporary tunnel.

Get All Webhooks for a List

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks' \
-H 'Authorization: Bearer secretsquirrel'

[
  {
    "id": 5,
    "url": "http://example.org/webhooks",
    "subscriptions": [
      "*"
    ],
    "enabled": true,
    "created_at": "2023-08-30T11:49:10Z",
    "updated_at": "2023-08-30T11:49:10Z"
  },
  {
    "id": 6,
    "url": "https://example.app/webhooks",
    "subscriptions": [
      "*"
    ],
    "enabled": true,
    "created_at": "2023-08-30T11:49:11Z",
    "updated_at": "2023-08-30T11:49:11Z"
  }
]

Gets all the a webhooks that are subscribed for a particular list. Webhook events will be will be sent to the provided URL.

HTTP Request

GET https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅

Create Webhook Subscription for a List

curl -L 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{
    "webhook" : {
        "url": "http://example.biz/webhooks"
    }
}'

{
  "id": 6,
  "url": "https://example.biz/webhooks",
  "subscriptions": [
    "*"
  ],
  "enabled": true,
  "created_at": "2023-08-30T11:49:11Z",
  "updated_at": "2023-08-30T11:49:11Z"
}

Creates a webhook subscription for a particular list.

HTTP Request

POST https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅

Body Parameters

Parameter	Description	Required
webhook	The block that contains the webhook parms	✅

webhook Parameters

Parameter	Description	Required
url	The url of where to send webhook events to	✅

Delete Webhook Subscription via ID

curl -L -X DELETE 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks/:webhook_id' \
-H 'Authorization: Bearer secretsquirrel' \
-d ''

Deletes a webhook subscription via the webhook id.

HTTP Request

DELETE https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks/:webhook_id

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅
webhook_id	The ID of the webhook	✅

Delete Webhook Subscription via URL

curl -L -X DELETE 'https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks/unsubscribe' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer secretsquirrel' \
-d '{
    "url": "http://example.app/webhooks"
}'

Deletes a webhook subscription via the webhook url. If the URL is not found to be subscribed, a 404 will be returned. Please note, a url with a trailing slash is not the same as a url without a trailing slash. Check to see what url's you have registered via the get all webhooks for a list api call.

HTTP Request

DELETE https://api.listomo.com/v1/accounts/:account_id/lists/:list_id/webhooks/unsubscribe

URL Parameters

Parameter	Description	Required
account_id	The ID of the account	✅
list_id	The ID of the list	✅

Body Parameters

Parameter	Description	Required
url	The url to unsubscribe	✅

Errors / Status Codes

The Listomo API uses the following status/error codes:

Error Code	Meaning
200	Ok
201	Created
204	Ok - No Content
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified resource could not be found.
422	Unprocessabile Entity -- Your request was not formatted correctly
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're being rate limited. The Listomo API rate limit is 30 requests per 10 seconds.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.