Communication

Auth required: Yes (auth:api) for all endpoints.

The Communication module covers two domains: Newsletters (mass email campaigns to contact lists) and Surveys (customer satisfaction surveys with branching logic and reply tracking).

Newsletters

Base URL: /api/v1/newsletters

Newsletters are mass emails sent to contact lists. A newsletter can be standalone or part of a campaign.

Model Properties

Property	Type	Required	Description
`id`	integer	auto	Unique identifier
`title`	string	Yes	Newsletter title (max 255 chars)
`body`	string	Yes (create)	HTML email body
`language_id`	integer	No	FK to languages
`brand_id`	integer	No	FK to brands
`target`	string	No	Target audience descriptor
`tags`	json	No	Array of tag strings
`status_id`	integer	No	FK to newsletter statuses
`send_at`	datetime	No	Scheduled send time
`sent_at`	datetime	auto	When the newsletter was actually sent
`created_at`	datetime	auto	Creation timestamp
`updated_at`	datetime	auto	Last update timestamp

GET /v1/newsletters

List all newsletters.

Response 200: Array of newsletter objects.

POST /v1/newsletters

Create a new newsletter.

Body (JSON): Newsletter attributes. title (max 255) and body are required.

Response 201: Created newsletter object. Response 422: Validation error.

GET /v1/newsletters/{id}

Show a single newsletter.

Response 200: Newsletter object. Response 404: Not found.

PUT /v1/newsletters/{id}

Update a newsletter.

Response 200: Updated newsletter object. Response 404: Not found. Response 422: Validation error.

DELETE /v1/newsletters/{id}

Delete a newsletter.

Response 200: Success. Response 404: Not found.

POST /v1/newsletters/{id}/test

Send a test email for the newsletter to the authenticated user and record the send.

Response 201: Success. Response 404: Not found.

Newsletter Lists

Base URL: /api/v1/newsletter-lists

Newsletter lists are collections of contacts targeted by newsletters.

GET /v1/newsletter-lists

List all newsletter lists with their contacts.

Response 200: Array of list objects with contacts (including related data).

POST /v1/newsletter-lists

Create a newsletter list.

Response 201: Created list object.

GET /v1/newsletter-lists/{id}

Show a newsletter list with contacts.

Response 200: List object with contacts. Response 404: Not found.

PUT /v1/newsletter-lists/{id}

Update a newsletter list and sync its contacts.

Response 200: Updated list object. Response 404: Not found.

DELETE /v1/newsletter-lists/{id}

Delete a newsletter list.

Response 200: Success. Response 404: Not found.

Newsletter Campaigns

Base URL: /api/v1/newsletter-campaigns

Campaigns group newsletters together and track aggregate delivery statistics.

Model Properties

Property	Type	Description
`id`	integer	Unique identifier
`name`	string	Campaign name
`records_count`	integer	Number of contacts targeted
`clicked`	integer	Number of click-through actions
`delivered`	integer	Number of successfully delivered emails
`opened`	integer	Number of emails opened
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

GET /v1/newsletter-campaigns

List all campaigns.

Response 200: Array of campaign objects.

POST /v1/newsletter-campaigns

Create a campaign.

Response 201: Created campaign object.

GET /v1/newsletter-campaigns/{id}

Show a campaign.

Response 200: Campaign object. Response 404: Not found.

PUT /v1/newsletter-campaigns/{id}

Update a campaign.

Response 200: Updated campaign object.

DELETE /v1/newsletter-campaigns/{id}

Delete a campaign.

Response 200: Success.

Surveys

Base URL: /api/v1/surveys

Surveys are customer satisfaction forms with branching logic. A survey contains branches, which contain groups, which contain questions (with propositions for multiple-choice types).

Survey Model Properties

Property	Type	Required	Description
`id`	integer	auto	Unique identifier
`subject`	string	Yes	Survey subject (min 3, max 255 chars)
`active`	boolean	No	Whether the survey is active (default: `false`)
`user_id`	integer	auto	FK to the user who created the survey
`created_at`	datetime	auto	Creation timestamp
`updated_at`	datetime	auto	Last update timestamp

GET /v1/surveys

List all surveys (lightweight resource).

Response 200: Array of survey objects (light format, without nested branches).

POST /v1/surveys

Create a survey. A default main branch is automatically created.

Body (JSON):

Field	Type	Required	Description
`subject`	string	Yes	Survey subject (min 3, max 255 chars)
`active`	boolean	No	Whether to activate the survey

Response 201: Created survey object.

GET /v1/surveys/{id}

Show a survey with branches.

Response 200: Survey object with branches. Response 404: Not found.

PUT /v1/surveys/{id}

Update a survey.

Response 200: Updated survey object.

DELETE /v1/surveys/{id}

Delete a survey.

Response 200: Success.

Survey Branches

Base URL: /api/v1/survey-branches

Branches are segments of a survey (e.g. a conditional path). Each branch contains groups.

GET /v1/survey-branches

List branches, optionally filtered by survey.

Query parameters:

Parameter	Type	Required	Description
`survey_id`	integer	No	Filter by survey ID

Response 200: Array of branch objects with groups.

Standard CRUD: `/v1/survey-branches[/{id}]`

Endpoint	Method	Description
`/v1/survey-branches`	GET	List branches
`/v1/survey-branches`	POST	Create a branch
`/v1/survey-branches/{id}`	GET	Show a branch
`/v1/survey-branches/{id}`	PUT	Update a branch
`/v1/survey-branches/{id}`	DELETE	Delete a branch

Survey Groups

Base URL: /api/v1/survey-groups

Groups are collections of questions within a branch.

Endpoint	Method	Description
`/v1/survey-groups`	GET	List groups (filterable by `branch_id`)
`/v1/survey-groups`	POST	Create a group. Validates that the `branch_id` exists and automatically merges the survey ID
`/v1/survey-groups/{id}`	GET	Show a group
`/v1/survey-groups/{id}`	PUT	Update a group
`/v1/survey-groups/{id}`	DELETE	Delete a group

Survey Questions

Base URL: /api/v1/survey-questions

GET /v1/survey-questions/types

Get the list of available question types.

Response 200: Array of question type strings.

GET /v1/survey-questions

List questions, optionally filtered by group_id.

Response 200: Array of question objects.

POST /v1/survey-questions

Create a question. Validates the type against allowed question types.

Body (JSON):

Field	Type	Required	Description
`type`	string	Yes	Question type (must be in the allowed types list)
`label`	string	Yes	Question text
`group_id`	integer	Yes	FK to survey group

Standard CRUD: `/v1/survey-questions[/{id}]`

Endpoint	Method	Description
`/v1/survey-questions/{id}`	GET	Show a question
`/v1/survey-questions/{id}`	PUT	Update a question
`/v1/survey-questions/{id}`	DELETE	Delete a question

Survey Propositions

Base URL: /api/v1/survey-propositions

Propositions are the answer options for multiple-choice questions.

Endpoint	Method	Description
`/v1/survey-propositions`	GET	List propositions
`/v1/survey-propositions`	POST	Create a proposition
`/v1/survey-propositions/{id}`	GET	Show a proposition
`/v1/survey-propositions/{id}`	PUT	Update a proposition
`/v1/survey-propositions/{id}`	DELETE	Delete a proposition

Survey Records

Base URL: /api/v1/survey-records

Survey records are completed survey responses submitted by customers.

Endpoint	Method	Description
`/v1/survey-records`	GET	List survey records (with reply-to-survey-request relationships)
`/v1/survey-records/{id}`	GET	Show a survey record
`/v1/survey-records/{id}`	DELETE	Delete a survey record

Survey Reply Requests

Base URL: /api/v1/survey-reply-requests

Reply requests track survey invitations sent to contacts (or other surveyable entities) and their response status.

GET /v1/survey-reply-requests

List reply requests with QueryBuilder filtering and sorting.

Query parameters (filters):

Parameter	Type	Description
`filter[score]`	numeric	Filter by NPS score
`filter[replied]`	boolean	Filter by whether the contact has replied
`filter[tries]`	integer	Filter by number of send attempts
`filter[created_at_from]`	date	Filter records created after this date
`filter[created_at_to]`	date	Filter records created before this date
`filter[updated_at_from]`	date	Filter records updated after this date
`filter[updated_at_to]`	date	Filter records updated before this date

Sortable fields: score, updated_at, tries, created_at, replied_at

Response 200: Paginated list of reply request objects with polymorphic surveyable relationships (Contact, CustomerFile, Ticket).

Newsletters

Model Properties

GET /v1/newsletters

POST /v1/newsletters

GET /v1/newsletters/{id}

PUT /v1/newsletters/{id}

DELETE /v1/newsletters/{id}

POST /v1/newsletters/{id}/test

Newsletter Lists

GET /v1/newsletter-lists

POST /v1/newsletter-lists

GET /v1/newsletter-lists/{id}

PUT /v1/newsletter-lists/{id}

DELETE /v1/newsletter-lists/{id}

Newsletter Campaigns

Model Properties

GET /v1/newsletter-campaigns

POST /v1/newsletter-campaigns

GET /v1/newsletter-campaigns/{id}

PUT /v1/newsletter-campaigns/{id}

DELETE /v1/newsletter-campaigns/{id}

Surveys

Survey Model Properties

GET /v1/surveys

POST /v1/surveys

GET /v1/surveys/{id}

PUT /v1/surveys/{id}

DELETE /v1/surveys/{id}

Survey Branches

GET /v1/survey-branches

Standard CRUD: /v1/survey-branches[/{id}]

Survey Groups

Survey Questions

GET /v1/survey-questions/types

GET /v1/survey-questions

POST /v1/survey-questions

Standard CRUD: /v1/survey-questions[/{id}]

Survey Propositions

Survey Records

Survey Reply Requests

GET /v1/survey-reply-requests

GET /v1/survey-reply-requests/customers

GET /v1/survey-reply-requests/export

GET /v1/survey-reply-requests/{id}

Standard CRUD: `/v1/survey-branches[/{id}]`

Standard CRUD: `/v1/survey-questions[/{id}]`