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'organisation | Cet endpoint |
|---|---|
OWNER | Autorisé |
ADMIN | Autorisé |
MEMBER | Refusé — 403 |
Corps de la requête
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
key | string | oui | Lettres minuscules, chiffres et _, commençant par une lettre, 40 caractères au plus. Unique dans l'organisation |
label | string | oui | De 1 à 100 caractères |
type | string | oui | text, 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 :detailsporte les erreurs champ par champ. Aussi, sansdetails, 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é estmemberde l'organisation, pasadmin.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
| Champ | Type | Description |
|---|---|---|
success | boolean | Indique si l'opération a réussi |
data.id | string | Identifiant unique du champ |
data.key | string | La clé sous laquelle s'écrivent les valeurs |
data.label | string | Le nom que l'on lit |
data.type | string | text, number, date ou boolean |
data.createdAt | string | Date de création ISO |
data.updatedAt | string | Date 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'un409, 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.