Перейти к содержимому

setEmailFlags

Обновлено 18 октября 2026

Содержание
  1. Параметры
  2. Флаги
  3. Пример запроса
  4. Пример ответа
  5. Поля ответа
  6. Ещё примеры
  7. Снять ключевое слово
  8. Ошибки
  9. Что дальше

Ставит и снимает у писем флаги как есть: системные флаги IMAP и свои ключевые слова. Привычные отметки удобнее менять методом markEmails.
Запрос POST /v1/instances/{idInstance}/setEmailFlags
Ключ заголовок Authorization: Bearer {apiTokenInstance}
Тело JSON
Каналы почта

Параметры

Параметр Тип Обязательный Описание
messages, folder + uids, idMessages array да, одно из письма — до 500; одно письмо — folder + uid, idMessage или messageId. См. Почта через API
add array, string нет какие флаги поставить: список или строка через запятую
remove array, string нет какие флаги снять
chatId string нет адрес собеседника — если письма указаны по idMessage

Нужен хотя бы один из add, remove.

Флаги

Флаг Как указать
прочитано seen или \Seen
флажок flagged или \Flagged
отвечено answered или \Answered
черновик draft или \Draft
своё ключевое слово как есть: латиница, цифры и _ . $ : -, до 64 знаков — $Important, crm-1532

В JSON обратная косая черта удваивается: "\\Seen". Свои ключевые слова хранит сервер почты, и не каждый сервер их принимает — проверьте, что слово появилось в flags конверта.

Пример запроса

Флажок и ключевое слово $Important:

curl

curl -X POST "$GRATIO_URL/v1/instances/$GRATIO_ID/setEmailFlags" \
  -H "Authorization: Bearer $GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "folder": "inbox",
    "uids": [
      1540
    ],
    "add": [
      "flagged",
      "$Important"
    ]
  }'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/v1/instances/{os.environ['GRATIO_ID']}"
HEADERS = {"Authorization": f"Bearer {os.environ['GRATIO_TOKEN']}"}

url = f"{BASE}/setEmailFlags"
payload = {"folder": "inbox", "uids": [1540], "add": ["flagged", "$Important"]}
response = requests.post(url, json=payload, headers=HEADERS, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/v1/instances/${GRATIO_ID}`;
const auth = { Authorization: `Bearer ${GRATIO_TOKEN}` };

const url = `${base}/setEmailFlags`;
const payload = { folder: "inbox", uids: [1540], add: ["flagged", "$Important"] };
const response = await fetch(url, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/v1/instances/' . getenv('GRATIO_ID');
$auth = 'Authorization: Bearer ' . getenv('GRATIO_TOKEN');
$url = $base . '/setEmailFlags';
$payload = [
    'folder' => 'inbox',
    'uids' => [1540],
    'add' => ['flagged', '$Important'],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [$auth, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Пример ответа

Ответ 200 OK:

{"updated": 1}

Поля ответа

Поле Тип Описание
updated integer сколько писем обработано

Ещё примеры

Снять ключевое слово

curl -X POST "$GRATIO_URL/v1/instances/$GRATIO_ID/setEmailFlags" \
  -H "Authorization: Bearer $GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "idMessages": [
      "7877cd439c05bc16617b"
    ],
    "remove": [
      "$Important"
    ]
  }'

Ошибки

Код code Когда Что делать
400 validation нет add и remove; не указаны письма; писем больше 500 исправить запрос
400 bad_flag флаг с недопустимыми знаками: кириллица, пробел латиница, цифры и _ . $ : -
400 not_found письма нет указать folder и uid из getEmails
400 folder_not_found нет папки folder проверить getFolders
400 mail_error сервер почты не принял флаг см. message — там ответ сервера
400 not_authorized ящик не подключён подключить ящик: connectMailbox
501 not_supported канал — не почта вызвать у канала «Почта»

Общие правила — в статье Ответы и ошибки.

Что дальше

  • markEmails — прочитано, флажок, отвечено.
  • getEmails — флаги писем в поле flags.

Была ли статья полезна?

Похожие статьи