Пользовательское поле электронной почты

Создайте поля электронной почты для хранения и проверки адресов электронной почты

Пользовательские поля электронной почты позволяют вам хранить адреса электронной почты в записях с встроенной проверкой. Они идеально подходят для отслеживания контактной информации, адресов электронной почты назначенных лиц или любых данных, связанных с электронной почтой, в ваших проектах.

Простой пример

Создайте простое поле электронной почты:

mutation CreateEmailField {
  createCustomField(input: {
    name: "Contact Email"
    type: EMAIL
  }) {
    id
    name
    type
  }
}

Расширенный пример

Создайте поле электронной почты с описанием:

mutation CreateDetailedEmailField {
  createCustomField(input: {
    name: "Client Email"
    type: EMAIL
    description: "Primary email address for client communications"
  }) {
    id
    name
    type
    description
  }
}

Входные параметры

CreateCustomFieldInput

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя поля электронной почты
`type`	CustomFieldType!	✅ Да	Должен быть `EMAIL`
`description`	String	Нет	Текст помощи, отображаемый пользователям

Установка значений электронной почты

Чтобы установить или обновить значение электронной почты в записи:

mutation SetEmailValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    text: "john.doe@example.com"
  }) {
    id
    customField {
      value  # Returns { text: "john.doe@example.com" }
    }
  }
}

Параметры SetTodoCustomFieldInput

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	ID записи для обновления
`customFieldId`	String!	✅ Да	ID пользовательского поля электронной почты
`text`	String	Нет	Адрес электронной почты для хранения

Создание записей с значениями электронной почты

При создании новой записи с значениями электронной почты:

mutation CreateRecordWithEmail {
  createTodo(input: {
    title: "Follow up with client"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "email_field_id"
      value: "client@company.com"
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # Email is accessed here as { text: "client@company.com" }
      }
    }
  }
}

Поля ответа

Ответ CustomField

Поле	Тип	Описание
`id`	ID!	Уникальный идентификатор для пользовательского поля
`name`	String!	Отображаемое имя поля электронной почты
`type`	CustomFieldType!	Тип поля (EMAIL)
`description`	String	Текст помощи для поля
`value`	JSON	Содержит значение электронной почты (см. ниже)
`createdAt`	DateTime!	Когда поле было создано
`updatedAt`	DateTime!	Когда поле было в последний раз изменено

Важно: Значения электронной почты доступны через поле customField.value.text, а не напрямую в ответе.

Запрос значений электронной почты

При запросе записей с пользовательскими полями электронной почты, доступ к электронной почте осуществляется через путь customField.value.text:

query GetRecordWithEmail {
  todo(id: "todo_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # For EMAIL type, contains { text: "email@example.com" }
      }
    }
  }
}

Ответ будет включать электронную почту в вложенной структуре:

{
  "data": {
    "todo": {
      "customFields": [{
        "customField": {
          "name": "Contact Email",
          "type": "EMAIL",
          "value": {
            "text": "john.doe@example.com"
          }
        }
      }]
    }
  }
}

Проверка электронной почты

Проверка формы

Когда поля электронной почты используются в формах, они автоматически проверяют формат электронной почты:

Использует стандартные правила проверки электронной почты
Удаляет пробелы из ввода
Отклоняет недопустимые форматы электронной почты

Правила проверки

Должен содержать символ @
Должен иметь действительный формат домена
Ведущие/замыкающие пробелы автоматически удаляются
Принимаются распространенные форматы электронной почты

Примеры действительных адресов электронной почты

user@example.com
john.doe@company.co.uk
test+tag@domain.org
first.last@sub.domain.com

Примеры недействительных адресов электронной почты

plainaddress          # Missing @ symbol
@domain.com          # Missing local part
user@                # Missing domain
user@domain          # Missing TLD
user name@domain.com # Spaces not allowed

Важные заметки

Прямой API против форм

Формы: Применяется автоматическая проверка электронной почты
Прямой API: Нет проверки - можно хранить любой текст
Рекомендация: Используйте формы для ввода пользователем, чтобы обеспечить проверку

Формат хранения

Адреса электронной почты хранятся в виде обычного текста
Без специального форматирования или разбора
Чувствительность к регистру: пользовательские поля электронной почты хранятся с учетом регистра (в отличие от адресов электронной почты для аутентификации пользователей, которые нормализуются в нижний регистр)
Нет ограничений по максимальной длине, кроме ограничений базы данных (лимит 16 МБ)

Необходимые разрешения

Действие	Необходимое разрешение
Create email field	`OWNER` or `ADMIN` project-level role
Update email field	`OWNER` or `ADMIN` project-level role
Delete email field	`OWNER` or `ADMIN` project-level role
Set email value	Any role except `VIEW_ONLY` and `COMMENT_ONLY`
View email value	Any project role with field access

Ответы на ошибки

Неверный формат электронной почты (только формы)

{
  "errors": [{
    "message": "ValidationError",
    "extensions": {
      "code": "BAD_USER_INPUT",
      "data": {
        "errors": [{
          "field": "email",
          "message": "Email format is invalid"
        }]
      }
    }
  }]
}

Поле не найдено

{
  "errors": [{
    "message": "Custom field not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

Общие случаи использования

Управление контактами
- Адреса электронной почты клиентов
- Контактная информация поставщиков
- Адреса электронной почты членов команды
- Контактные данные для поддержки
Управление проектами
- Адреса электронной почты заинтересованных сторон
- Адреса электронной почты для одобрения
- Получатели уведомлений
- Адреса электронной почты внешних сотрудников
Поддержка клиентов
- Адреса электронной почты клиентов
- Контакты по заявкам на поддержку
- Контакты для эскалации
- Адреса электронной почты для обратной связи
Продажи и маркетинг
- Адреса электронной почты потенциальных клиентов
- Списки контактов для кампаний
- Контактная информация партнеров
- Адреса электронной почты источников рекомендаций

Функции интеграции

С автоматизацией

Запуск действий при обновлении полей электронной почты
Отправка уведомлений на сохраненные адреса электронной почты
Создание задач для последующих действий на основе изменений электронной почты

С поиском

Ссылка на данные электронной почты из других записей
Агрегация списков электронной почты из нескольких источников
Поиск записей по адресу электронной почты

С формами

Автоматическая проверка электронной почты
Проверка формата электронной почты
Удаление пробелов

Ограничения

Нет встроенной проверки или валидации электронной почты, кроме проверки формата
Нет специфических функций пользовательского интерфейса для электронной почты (например, кликабельные ссылки на электронную почту)
Хранится в виде обычного текста без шифрования
Нет возможности составления или отправки электронной почты
Нет хранения метаданных электронной почты (отображаемое имя и т. д.)
Прямые вызовы API обходят проверку (только формы проверяются)

Связанные ресурсы

Текстовые поля - Для неэлектронных текстовых данных
URL-поля - Для адресов веб-сайтов
Телефонные поля - Для номеров телефонов
Обзор пользовательских полей - Общие концепции