«API разработчика»

Обзор

API разработчика Nudgen предоставляет сценариям, внутренним инструментам и агентам искусственного интеллекта предсказуемый интерфейс REST для вашего рабочего пространства. Используйте токен личного доступа (PAT) для управления ресурсами рабочей области. Используйте ключ API триггера команды только для запуска пожизненной кампании из вашего серверного интерфейса.

Почему это важно

Вы можете автоматизировать рабочие процессы маркетинга и хранения на основе событий, не открывая сеанс информационной панели. PAT обеспечивают возможность отзыва управления рабочей областью, а узкий ключ триггера Team позволяет производственной службе отправлять инициируемый событием запрос без широкого доступа к рабочей области.

Базовый URL-адрес

Один раз задайте URL-адрес приложения для своей среды и используйте его в каждом примере. В производстве обычно используется https://app.nudgen.net; локальная разработка обычно использует http://localhost:3000.

export NUDGEN_APP_URL="https://app.nudgen.net"

Аутентификация

Токен личного доступа

Создайте PAT в Настройки → Ключи API. Используйте его для контактов, управления кампаниями, настроек бренда и создания искусственного интеллекта.

Authorization: Bearer $NUDGEN_PAT

PAT отображаются только один раз. Храните их в надежном месте и отзовите любой старый или открытый токен из Настройки → Ключи API.

API-ключ группового триггера

Ключ API группового триггера начинается с ndg_team_ и имеет узкую область действия campaigns:trigger. Он может запускать только пожизненные кампании; PAT не может активировать их. Только владельцы и администраторы рабочих пространств могут создавать, менять или отзывать эти ключи. По умолчанию срок действия ключа истекает через 90 дней. Установите для expiresInDays значение null, чтобы создать ключ с неограниченным сроком действия.

curl -X POST "$NUDGEN_APP_URL/api/v1/settings/team-api-keys" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"name":"Order service production","expiresInDays":90}'

Ответ 201 содержит открытый текст key ровно один раз. Сохраните его в секретном менеджере на стороне сервера. Более поздние ответы раскрывают только keyPrefix.

Метод	Конечная точка	Описание
`POST`	`/api/v1/settings/team-api-keys`	Создайте ключ API триггера группы.
`GET`	`/api/v1/settings/team-api-keys`	Список ключей API триггера команды.
`POST`	`/api/v1/settings/team-api-keys/:id`	Поверните активный ключ с неистекшим сроком действия.
`DELETE`	`/api/v1/settings/team-api-keys/:id`	Отозвать ключ.

Конечные точки REST

Идентификация и рабочее пространство

Метод	Конечная точка	Описание
`GET`	`/api/v1/user/me`	Получите аутентифицированного пользователя.
`GET`	`/api/v1/teams`	Перечислите рабочие области, доступные владельцу токена.

Контакты

Метод	Конечная точка	Описание
`GET`	`/api/v1/contacts`	Выведите список контактов с помощью фильтров `page`, `limit`, `search`, `tags` и `status`.
`POST`	`/api/v1/contacts/add`	Создайте контакт.
`GET`	`/api/v1/contacts/:id`	Получите контакт.
`PATCH`	`/api/v1/contacts/:id`	Обновите контакт.
`DELETE`	`/api/v1/contacts/:id`	Удалить контакт.

curl -X POST "$NUDGEN_APP_URL/api/v1/contacts/add" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"email":"nathan@example.com","name":"Nathan Nguyen","tags":["api-test"]}'

Разовые и капельные кампании

Метод	Конечная точка	Описание
`GET`	`/api/v1/campaigns`	Перечислите кампании в активной рабочей области.
`POST`	`/api/v1/campaigns`	Создайте проект кампании или запланированную кампанию.
`GET`	`/api/v1/campaigns/:id`	Получите подробную информацию о кампании.
`PUT`	`/api/v1/campaigns/:id`	Обновите существующую кампанию.
`POST`	`/api/v1/campaigns/:id/launch`	Запустите сейчас или запланируйте разовую или капельную кампанию.
`GET`	`/api/v1/campaigns/:id/stats`	Получайте статистику доставки, открытия, кликов, отказов и жалоб.
`GET`	`/api/v1/campaigns/:id/progress`	Получите информацию о ходе отправки кампании.
`GET`	`/api/v1/campaigns/:id/recipients`	Перечислите получателей кампании.
`POST`	`/api/v1/campaigns/test-send`	Отправьте тестовое электронное письмо без отправки статистики на панель управления.

При запуске кампании планируется реальная электронная почта. Используйте /api/v1/campaigns/test-send для предварительного просмотра входящих сообщений.

Пожизненные кампании

Пожизненные кампании активируются по событию: каждый принятый триггер создает не более одного выполнения и отправляет одно напоминание указанному контакту. См. Использование пожизненных кампаний для получения информации о рабочем процессе информационной панели и руководствах по переменному контракту.

Создайте пожизненную кампанию

Создавайте пожизненные кампании как draft. Не отправляйте sendNow: true, status: "active" или status: "scheduled"; Вместо этого активируйте кампанию с помощью конечной точки жизненного цикла.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "Order confirmation",
  "type": "lifetime",
  "status": "draft",
  "goal": "Confirm an order and direct the customer to its details.",
  "subject": "Your order {{data.order_id}} was received",
  "html": "<p>Hello {{contact.firstName}},</p><p>Order {{data.order_id}} totals {{data.total}} VND.</p><p><a href=\"{{data.order_url}}\">View your order</a></p>",
  "link": "https://example.com/orders",
  "variableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ],
  "generatedVariableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ]
}
JSON

variableManifest определяет до 100 переменных data.*. Он должен включать каждый токен data.*, используемый в теме или HTML. Значения по умолчанию должны соответствовать объявленному типу, а переменная, используемая в HTML-коде href, должна иметь тип url. При создании содержимого электронной почты сохраните соответствующий generatedVariableManifest. Nudgen блокирует активацию, если она отличается от текущего манифеста или если в письме отсутствуют обязательные заявленные параметры.

Изменить жизненный цикл

Метод	Конечная точка	Аутентификация	Описание
`PATCH`	`/api/v1/campaigns/:campaignId/lifecycle`	ПАТ	Измените пожизненную кампанию на `active`, `paused` или `archived`.

curl -X PATCH "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/lifecycle" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"status":"active"}'

Допустимыми переходами являются draft → active → paused → active и active|paused → archived. Приостановка или архивирование отменяет выполнения, которые все еще имеют статус pending или queued, и освобождает их резервирования квот. Выполнение, которое уже обрабатывается, все еще может быть отправлено.

Вызов подталкивания

Метод	Конечная точка	Аутентификация	Описание
`POST`	`/api/v1/campaigns/:campaignId/triggers`	Ключ API триггера команды	Создайте одно выполнение события и поставьте подталкивание в очередь.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/triggers" \
  -H "Authorization: Bearer $NUDGEN_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "eventId": "order_123",
  "eventName": "order.created",
  "occurredAt": "2026-08-23T10:00:00Z",
  "contact": {
    "email": "an@example.com",
    "externalId": "customer_456",
    "name": "An Nguyen",
    "phone": "+84901234567",
    "metadata": { "company": "Nudgen" }
  },
  "data": {
    "order_id": "order_123",
    "total": 490000,
    "order_url": "https://example.com/orders/order_123"
  }
}
JSON

Поле	Тип	Требуется	Ограничения и поведение
`eventId`	строка	Да	1–128 символов. Уникальный ключ идемпотентности внутри кампании; повторно использовать его для повторных попыток.
`eventName`	строка	Нет	От 1 до 100 символов, например `order.created`.
`occurredAt`	ISO 8601 дата-время	Нет	Время исходного события.
`contact.email`	электронная почта	Да	В нижнем регистре. Nudgen создает или обновляет контакт по электронной почте.
`contact.externalId`	строка	Нет	Длина от 1 до 200 символов и не может принадлежать другому контактному адресу электронной почты в рабочей области.
`contact.name`	строка	Нет	До 200 символов.
`contact.phone`	строка	Нет	До 50 символов.
`contact.metadata`	объект	Нет	Дополнительные данные профиля контакта.
`data`	объект	Да	Должно соответствовать `variableManifest`; максимум 32 КиБ.

Размер всего тела запроса ограничен 64 КБ, вложенность JSON — до восьми уровней, а небезопасные ключи, такие как __proto__, constructor и prototype, отклоняются. Новый триггер возвращает 201 с { "execution": { "id": "...", "status": "queued" }, "duplicate": false }. Повторное использование eventId возвращает существующее выполнение с 200 и duplicate: true.

Список выполнений

Метод	Конечная точка	Аутентификация	Описание
`GET`	`/api/v1/campaigns/:campaignId/executions`	ПАТ	Составьте список выполненных кампаний за весь срок службы.

curl "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/executions?limit=25&status=sent&search=an@example.com" \
  -H "Authorization: Bearer $NUDGEN_PAT"

Используйте limit от 1 до 100 (по умолчанию 25), cursor для следующей страницы, status для фильтрации по статусу выполнения и search для соответствия адресу электронной почты или внешнему идентификатору. Ответ включает executions и nextCursor.

Ошибки, повторные попытки и ограничения скорости

Триггеры на весь срок службы допускают 600 запросов в минуту для каждого ключа API триггера Team. Ответы включают x-ratelimit-limit, x-ratelimit-remaining и x-ratelimit-reset. Ответ 429 также включает Retry-After.

Статус	Значение	Что делать
`200`	Дубликат `eventId`	Используйте возвращенное выполнение; больше не отправляйте.
`201`	Новое исполнение в очереди	Подождите, пока работник обработает его.
`400`	Неверный JSON, текст или базовое поле	Исправьте полезную нагрузку; не повторяйте попытку без изменений.
`401`	Ключ отсутствует, недействителен, отозван, срок его действия истек или имеет неверную область действия	Поверните или исправьте конфигурацию клавиш.
`402` / `403`	Квота или подписка предотвращает запись	Решите проблему с квотой или подпиской. К ошибкам квоты относятся `code`, `required`, `available` и `checkoutUrl`.
`404`	Кампания отсутствует или находится за пределами рабочей области ключа	Проверьте идентификатор и ключ кампании.
`409`	Кампания не активна/не бессрочна, или конфликты контактных данных	Активируйте кампанию или исправьте контактную информацию.
`413`	Запрос превышает 64 КиБ	Уменьшите размер полезной нагрузки.
`415`	Отсутствует `Content-Type: application/json`	Добавьте необходимый заголовок.
`422`	`data` не соответствует манифесту переменной	Исправьте данные; проверьте `details` на наличие путей и кодов ошибок.
`429`	Превышен лимит скорости	Подождите `Retry-After`, затем повторите попытку с тем же `eventId`.
`503`	Выполнение не может быть поставлено в очередь	Повторите попытку с отсрочкой и тем же `eventId`.

Для 429, 503 и сетевых ошибок повторите попытку с экспоненциальной отсрочкой и тем же eventId. Задание в очереди является детерминированным для выполнения, поэтому повторные попытки не создают дубликатов электронных писем.

Настройки бренда

Метод	Конечная точка	Описание
`GET`	`/api/v1/settings/brand`	Прочитайте название бренда, веб-сайт, адрес электронной почты отправителя, логотип и настройки дизайна.
`PATCH`	`/api/v1/settings/brand`	Обновите настройки бренда.

Генерация проектов ИИ

Метод	Конечная точка	Описание
`POST`	`/api/v1/ai/generate`	Создайте тему электронного письма и черновик HTML на основе контекста кампании.

Сервер MCP

Используйте Nudgen MCP, если ваш агент поддерживает инструменты протокола контекста модели. MCP использует тот же PAT, что и API управления рабочей областью, но предоставляет Nudgen в качестве инструментов, вызываемых агентом, вместо обычных конечных точек HTTP.

MCP server setup

Установите Nudgen MCP в Claude Code, Cursor, Windsurf, Codex CLI или в обычном клиенте MCP.

Начало работы

Контакты

Кампании

Бреند

Панель управления

Настройки

Биллинг

Партнерская программа

Agents

Поиск Email (Расширение)

Генератор подписей

Проверка на спам

Аудит доставляемости

Концепции

Устранение неполадок

Безопасность

Юридическая информация

«API разработчика»

Обзор

Почему это важно

Базовый URL-адрес

Аутентификация

Токен личного доступа

API-ключ группового триггера

Конечные точки REST

Идентификация и рабочее пространство

Контакты

Разовые и капельные кампании

Пожизненные кампании

Создайте пожизненную кампанию

Изменить жизненный цикл

Вызов подталкивания

Список выполнений

Ошибки, повторные попытки и ограничения скорости

Настройки бренда

Генерация проектов ИИ

Сервер MCP

MCP server setup

​Обзор

​Почему это важно

​Базовый URL-адрес

​Аутентификация

​Токен личного доступа

​API-ключ группового триггера

​Конечные точки REST

​Идентификация и рабочее пространство

​Контакты

​Разовые и капельные кампании

​Пожизненные кампании

​Создайте пожизненную кампанию

​Изменить жизненный цикл

​Вызов подталкивания

​Список выполнений

​Ошибки, повторные попытки и ограничения скорости

​Настройки бренда

​Генерация проектов ИИ

​Сервер MCP

MCP server setup

Обзор

Почему это важно

Базовый URL-адрес

Аутентификация

Токен личного доступа

API-ключ группового триггера

Конечные точки REST

Идентификация и рабочее пространство

Контакты

Разовые и капельные кампании

Пожизненные кампании

Создайте пожизненную кампанию

Изменить жизненный цикл

Вызов подталкивания

Список выполнений

Ошибки, повторные попытки и ограничения скорости

Настройки бренда

Генерация проектов ИИ

Сервер MCP