Créer un champ personnalisé

POST /api/v1/custom-fields Crée un champ personnalisé. Répond 201 avec le champ créé — dès lors, les contacts acceptent une valeur sous sa key. La key et le type sont fixés à la création : choisissez-les avec soin, seul le libellé se renomme ensuite.

Autorisation

Rôle dans l'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERRefusé — 403
Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Corps de la requête

ChampTypeObligatoireDescription
keystringouiLettres minuscules, chiffres et _, commençant par une lettre, 40 caractères au plus. Unique dans l'organisation
labelstringouiDe 1 à 100 caractères
typestringouitext, number, date ou boolean (oui/non)
json
{"key": "utm_source", "label": "UTM source", "type": "text"}

Exemple

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"key":"utm_source","label":"UTM source","type":"text"}' \
  "https://www.agentsmail.io/api/v1/custom-fields"

Réponse

  • 201 Created — le champ créé.
  • 400 Bad Request — un champ manque, le libellé est trop long ou le type est inconnu : details porte les erreurs champ par champ. Aussi, sans details, quand la clé est mal formée (UTM-Source), quand elle est réservée (email, status…), ou quand l'organisation a déjà 50 champs — le message dit lequel.
  • 401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
  • 403 Forbidden — le propriétaire de la clé est member de l'organisation, pas admin.
  • 409 Conflict — un autre champ utilise déjà cette clé. Rien n'a été créé ; listez les champs et réutilisez celui qui existe.
  • 429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

ChampTypeDescription
successbooleanIndique si l'opération a réussi
data.idstringIdentifiant unique du champ
data.keystringLa clé sous laquelle s'écrivent les valeurs
data.labelstringLe nom que l'on lit
data.typestringtext, number, date ou boolean
data.createdAtstringDate de création ISO
data.updatedAtstringDate ISO de la dernière modification

Exemple de réponse

json
{
  "success": true,
  "data": {
    "id": "4f1a9c2e",
    "key": "utm_source",
    "label": "UTM source",
    "type": "text",
    "createdAt": "2026-11-15T10:22:05.000Z",
    "updatedAt": "2026-11-15T10:22:05.000Z"
  }
}

Recette pour agent

Réutiliser avant de créer — une clé déjà prise ne vous coûte qu'un 409, et un champ dont le type ne correspond pas à vos données ne peut plus être changé :
js
const existing = await list('/api/v1/custom-fields')
const field =
  existing.data.find((f) => f.key === 'utm_source') ??
  (await post('/api/v1/custom-fields', {
    key: 'utm_source',
    label: 'UTM source',
    type: 'text',
  })).data

await post(`/api/v1/lists/${listId}/contacts`, {
  email: 'ada@example.com',
  customFields: {[field.key]: 'newsletter'},
})

Remarques

  • Créer un champ n'écrit rien sur aucun contact : chaque contact commence sans valeur.

Voir aussi