Contact List

Organizza i contatti in liste denominate usate come obiettivi delle campagne.

📄️Cerca liste contatti

Returns a paginated list of contact lists in your account matching the provided filters. Contact lists are named groups of contacts that serve as the recipient audience for campaigns. A single contact can belong to multiple lists. Use the search parameter to find lists by name (case-insensitive partial match). Use id (comma-separated) to retrieve specific lists by their IDs. Use contactIds (comma-separated) to find all lists that contain specific contacts, which is useful for understanding which lists a contact is a member of. Set isTest=true to retrieve only test lists used for sending test campaigns, or isTest=false to exclude them. By default, deleted lists are excluded. Set includeDeleted=true to include soft-deleted lists in the results. Results are paginated: page is 0-based, limit defaults to 10 (maximum 1000). Use sortBy to choose the sort field (defaults to name) and sortOrder for asc or desc. Returns 500 if an unexpected server error occurs.

📄️Elimina liste contatti

Deletes one or more contact lists by their IDs. Provide the ids parameter as a comma-separated list of contact list IDs to delete. Deleting a contact list removes the list and all associations between that list and its contacts, but does not delete the contacts themselves. The contacts remain in your account and can still belong to other lists. If a deleted list is currently assigned to a draft or scheduled campaign, you should update that campaign to remove the deleted list from its contactListIds before confirming it, otherwise the campaign may fail validation. This operation is irreversible. Returns 200 with the result of the deletion operation. Returns 500 if an unexpected server error occurs.

📄️Crea una nuova lista contatti

Creates a new empty contact list in your account. A contact list is a named group that acts as a recipient audience for campaigns. You must provide at least a name for the list. After creating the list, populate it by adding contacts using POST /contacts/list/contacts (for existing contacts) or by importing contacts from a file with POST /contacts/upload or POST /contacts/upload/vcard (which can auto-assign imported contacts to the list). You can then assign the list to one or more campaigns by including its ID in the contactListIds field when creating or updating a campaign. Set the isTest flag to true if this list is intended for testing purposes only (e.g., sending test messages to internal recipients before launching a real campaign). Returns 201 with the created contact list details including the generated list ID. Returns 400 if the request body is missing required fields or contains invalid data. Returns 500 if an unexpected server error occurs.

📄️Rimuovi contatti dalle liste contatti

Removes contacts from contact lists in bulk by deleting their associations. The request body must include listIds (the target contact lists to remove contacts from) and either specific contactIds or allContacts=true. When allContacts is false, provide contactIds as a list of contact IDs to remove from the specified lists. The contactIds field is required in this mode. When allContacts is true, all contacts are removed from the specified lists, except those whose IDs are in excludeIdsAllContacts. This operation only removes the contact-to-list associations; it does not delete the contacts themselves or the lists. Contacts removed from a list will no longer be recipients of campaigns that target that list, unless they also belong to another list used by the same campaign. Use this to clean up list memberships, prepare lists for re-import, or narrow down a campaign audience. For deleting a single association by its ID, use DELETE /contacts/list/contacts/{id} instead. Returns 200 with the result of the dissociation operation. Returns 400 if listIds is empty, or if allContacts is false and contactIds is not provided. Returns 500 if an unexpected server error occurs.

📄️Aggiungi contatti alle liste contatti

Creates associations between contacts and contact lists, effectively adding contacts as members of the specified lists. The request body must include listIds (the target contact lists) and either specific contactIds or allContacts=true. When allContacts is false, provide contactIds as a list of contact IDs to add to the specified lists. When allContacts is true, all contacts in your account are added to the specified lists, except those whose IDs are in excludeIdsAllContacts. This is a bulk operation: you can add multiple contacts to multiple lists in a single call. If a contact is already a member of a given list, the existing association is preserved (no duplicate is created). After adding contacts to lists, the updated lists can be used as campaign audiences by including them in a campaign's contactListIds. Returns 201 with the IDs of the created associations. Returns 400 if listIds is empty or the request body is otherwise invalid. Returns 500 if an unexpected server error occurs.

📄️Elimina associazione per ID

Elimina una singola associazione tra un contatto e una lista contatti, identified by the association's numeric ID. This removes the contact from the list but does not delete the contact itself or the list. The association ID is a unique identifier for the link between a specific contact and a specific list. You can obtain association IDs from the response of POST /contacts/list/contacts when the associations were created. For bulk removal of contacts from lists, use DELETE /contacts/list/contacts/ instead, which supports removing multiple contacts at once. Returns 200 on successful deletion of the association. Returns 404 if no association exists with the given ID under your account. Returns 500 if an unexpected server error occurs.

📄️Aggiorna una lista contatti

Updates the metadata of an existing contact list identified by its numeric ID. You can modify the list name, description, and isTest flag. This endpoint only updates the list metadata; it does not add or remove contacts from the list. To add or remove contacts, use POST /contacts/list/contacts and DELETE /contacts/list/contacts/ respectively. If the list is currently assigned to a campaign, the campaign will automatically use the updated list metadata. Returns 200 with the updated contact list details. Returns 400 if the request body contains invalid data. Returns 404 if no contact list exists with the given ID under your account. Returns 500 if an unexpected server error occurs.

📄️Ottieni lista contatti per ID

Retrieves the full details of a single contact list by its numeric ID. The response includes the list name, description, creation date, contact count, and whether it is marked as a test list. Use this endpoint to inspect a list before assigning it to a campaign via POST /campaigns or PUT /campaigns/{id}. To retrieve the actual contacts within this list, use GET /contacts/list/{listId}/contacts. Returns 404 if no contact list exists with the given ID under your account. Returns 500 if an unexpected server error occurs.

📄️Cerca contatti in una lista contatti

Returns the contacts belonging to a specific contact list, with optional filters and pagination. This is a convenience endpoint equivalent to calling GET /contacts with the listIds parameter set to the given listId. All the same contact-level filters are available: search (case-insensitive text match against name), gender, isValid, communicationSupported (e.g., SMS, RCS, WHATSAPP), isTest, phoneNumber, email, lastContactType, and lastCampaignType. Results are paginated: page is 0-based, limit defaults to 10 (maximum 1000). Use sortBy to choose the sort field (defaults to fullName) and sortOrder for asc or desc. Use this endpoint to preview the audience of a contact list before assigning it to a campaign, or to verify which contacts were imported after a file upload. Returns 404 if no contact list exists with the given listId under your account. Returns 500 if an unexpected server error occurs.