Sending Surveys via Email

The Feedback Management API lets you collect feedback from your customers by email. You design a reusable email template, then send a campaign to a list of recipients. Each email links to one of your feedback forms, and the responses you collect feed back into Partoo’s Feedback Management.

Prerequisites

Before sending feedback emails, ensure you have:

A valid API key with access to Feedback Management.
At least one feedback form configured for your organization. The campaign links recipients to this form.
A sender email whose domain is authorized for your organization and validated for email sending. Contact your Account Manager if you are unsure whether your domain is set up.

How sending works

A feedback email campaign ties together three things: an email template (how the email looks), a feedback form (where responses are collected), and a recipient list (who receives it). Validation is all-or-nothing: if the sender email or any recipient fails validation, the entire campaign is rejected and no emails are sent. The response body details every error so you can fix the list and retry.

Step 0 — Create an email template (optional)

This step is optional. Most teams design their templates visually with the WYSIWYG editor in the Partoo Web app. If you already have a template, skip to Step 1.

curl -X POST 'https://api.partoo.co/v2/feedback/email-templates' \
  -H 'x-APIKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Default Template",
    "subject": "We'\''d love your feedback",
    "title": "How did we do?",
    "body": "Thank you for visiting us. Please take a moment to share your experience.",
    "cta_type": "BUTTON",
    "cta_text": "Leave a review",
    "color": "#3B82F6",
    "font_family": "Arial"
  }'

import requests

response = requests.post(
    "https://api.partoo.co/v2/feedback/email-templates",
    headers={
        "x-APIKey": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Default Template",
        "subject": "We'd love your feedback",
        "title": "How did we do?",
        "body": "Thank you for visiting us. Please take a moment to share your experience.",
        "cta_type": "BUTTON",
        "cta_text": "Leave a review",
        "color": "#3B82F6",
        "font_family": "Arial",
    },
)

template_id = response.json()["id"]

const response = await fetch(
  "https://api.partoo.co/v2/feedback/email-templates",
  {
    method: "POST",
    headers: {
      "x-APIKey": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Default Template",
      subject: "We'd love your feedback",
      title: "How did we do?",
      body: "Thank you for visiting us. Please take a moment to share your experience.",
      cta_type: "BUTTON",
      cta_text: "Leave a review",
      color: "#3B82F6",
      font_family: "Arial",
    }),
  },
);

const {id: templateId} = await response.json();

A successful response returns 201 Created with the template’s id. See the Create an email template API reference for the full field reference.

Step 1 — Get your email template ID

Templates built in the Partoo Web app are available to the API. List your organization’s templates to find the id you want to use.

curl -X GET 'https://api.partoo.co/v2/feedback/email-templates?page=1&per_page=30' \
  -H 'x-APIKey: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.partoo.co/v2/feedback/email-templates",
    headers={"x-APIKey": "YOUR_API_KEY"},
    params={"page": 1, "per_page": 30},
)

templates = response.json()["items"]
template_id = templates[0]["id"]

const params = new URLSearchParams({page: "1", per_page: "30"});

const response = await fetch(
  `https://api.partoo.co/v2/feedback/email-templates?${params}`,
  {headers: {"x-APIKey": "YOUR_API_KEY"}},
);

const {items} = await response.json();
const templateId = items[0].id;

See the List email templates API reference for the full response schema and pagination options.

Step 2 — Get your feedback form ID

Each campaign links recipients to one feedback form. Search your organization’s forms to find the feedback_form_id you want to use.

curl -X GET 'https://api.partoo.co/v2/feedback/feedback_form' \
  -H 'x-APIKey: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.partoo.co/v2/feedback/feedback_form",
    headers={"x-APIKey": "YOUR_API_KEY"},
)

feedback_form_id = response.json()["items"][0]["id"]

const response = await fetch(
  "https://api.partoo.co/v2/feedback/feedback_form",
  {
    headers: {"x-APIKey": "YOUR_API_KEY"},
  },
);

const {items} = await response.json();
const feedbackFormId = items[0].id;

See the Search for feedback forms API reference for details.

Step 3 — Get campaign requirements

Before sending, call the requirements endpoint with your feedback_form_id and template_id. It returns the exact recipient fields and template variables your payload must include, so you know which keys to provide for every recipient.

curl -X GET 'https://api.partoo.co/v2/feedback/campaign/requirements?feedback_form_id=5a3f8c2e1b4d7f9a0c6e2b18&template_id=42' \
  -H 'x-APIKey: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.partoo.co/v2/feedback/campaign/requirements",
    headers={"x-APIKey": "YOUR_API_KEY"},
    params={
        "feedback_form_id": "5a3f8c2e1b4d7f9a0c6e2b18",
        "template_id": 42,
    },
)

requirements = response.json()

const params = new URLSearchParams({
  feedback_form_id: "5a3f8c2e1b4d7f9a0c6e2b18",
  template_id: "42",
});

const response = await fetch(
  `https://api.partoo.co/v2/feedback/campaign/requirements?${params}`,
  {headers: {"x-APIKey": "YOUR_API_KEY"}},
);

const requirements = await response.json();

A typical response:

{
  "feedback_form_id": "5a3f8c2e1b4d7f9a0c6e2b18",
  "template_id": 42,
  "recipient_fields": ["email_address", "unsubscribe_url"],
  "variable_fields": ["first_name", "store_code"]
}

recipient_fields: Recipient-level fields supported by the send endpoint.
variable_fields: Template variable names each recipient must provide under variables (sorted alphabetically). In the example above, every recipient must supply first_name and store_code.

See the Get campaign requirements API reference for the full schema.

Step 4 — Validate with a dry run

A dry run uses the same send endpoint (POST /feedback/campaign/send) with is_dry_run: true. It validates the sender and recipients without sending any emails — the safest way to confirm your list is correct before a real send.

curl -X POST 'https://api.partoo.co/v2/feedback/campaign/send' \
  -H 'x-APIKey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "feedback_form_id": "5a3f8c2e1b4d7f9a0c6e2b18",
    "feedback_email_template_id": 42,
    "sender_email": "noreply@example.com",
    "sender_name": "Acme Corp",
    "is_dry_run": true,
    "recipients": [
      {
        "email_address": "john.doe@example.com",
        "variables": { "first_name": "John", "store_code": "PAR-01" }
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.partoo.co/v2/feedback/campaign/send",
    headers={
        "x-APIKey": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "feedback_form_id": "5a3f8c2e1b4d7f9a0c6e2b18",
        "feedback_email_template_id": 42,
        "sender_email": "noreply@example.com",
        "sender_name": "Acme Corp",
        "is_dry_run": True,
        "recipients": [
            {
                "email_address": "john.doe@example.com",
                "variables": {"first_name": "John", "store_code": "PAR-01"},
            }
        ],
    },
)

result = response.json()

const response = await fetch(
  "https://api.partoo.co/v2/feedback/campaign/send",
  {
    method: "POST",
    headers: {
      "x-APIKey": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      feedback_form_id: "5a3f8c2e1b4d7f9a0c6e2b18",
      feedback_email_template_id: 42,
      sender_email: "noreply@example.com",
      sender_name: "Acme Corp",
      is_dry_run: true,
      recipients: [
        {
          email_address: "john.doe@example.com",
          variables: {first_name: "John", store_code: "PAR-01"},
        },
      ],
    }),
  },
);

const result = await response.json();

The send endpoint returns 200 OK for both accepted and rejected campaigns. Always inspect the status field rather than relying on the HTTP status code.

status: "accepted" — validation passed (emails enqueued, or skipped because is_dry_run was true).
status: "failed" — sender or recipient validation failed; no emails were sent. The error fields describe what to fix.

See the Send a feedback email campaign API reference for the complete request and response schema.

Step 5 — Send the campaign

Once the dry run returns status: "accepted", send for real by setting is_dry_run: false (or omitting it — it defaults to false). A successful response:

{
  "status": "accepted",
  "feedback_email_campaign_id": 101,
  "feedback_form_id": "5a3f8c2e1b4d7f9a0c6e2b18",
  "feedback_template_id": 42,
  "recipient_count": 150
}

Batch limit: a single call accepts at most 1000 recipients. For larger lists, split them into batches and call the endpoint multiple times.

See the Send a feedback email campaign API reference for the complete request and response schema.

First Steps

Guides

Resources

Misc

Sending Surveys via Email

Prerequisites

How sending works

Step 0 — Create an email template (optional)

Step 1 — Get your email template ID

Step 2 — Get your feedback form ID

Step 3 — Get campaign requirements

Step 4 — Validate with a dry run

Step 5 — Send the campaign

​Prerequisites

​How sending works

​Step 0 — Create an email template (optional)

​Step 1 — Get your email template ID

​Step 2 — Get your feedback form ID

​Step 3 — Get campaign requirements

​Step 4 — Validate with a dry run

​Step 5 — Send the campaign

Prerequisites

How sending works

Step 0 — Create an email template (optional)

Step 1 — Get your email template ID

Step 2 — Get your feedback form ID

Step 3 — Get campaign requirements

Step 4 — Validate with a dry run

Step 5 — Send the campaign