Envois

Cette page décrit les contrats d'envoi de courriels associés aux courriers. Les routes de préparation de l'interface et les routes propres au connecteur d'envoi postal Maileva ne font pas partie du contrat intégrateur publié ici.

Créer un brouillon ou envoyer un courriel

Cette action crée un courriel. La valeur de status détermine si le courriel reste en brouillon ou entre dans le processus d'envoi.

POST /rest/emails

Authentification, privilège et périmètre

L'authentification REST et le privilège sendmail sont obligatoires. Lorsque le body référence un courrier, celui-ci doit appartenir au périmètre de l'utilisateur. Les pièces jointes et les notes doivent appartenir à ce courrier et être visibles par l'utilisateur.

L'adresse de l'expéditeur doit faire partie des adresses autorisées pour l'utilisateur. Une configuration de serveur de courriel doit être présente.

Body JSON

Valeur	Type	Obligatoire	Description
status	string	Oui	DRAFT conserve un brouillon. Toute autre valeur déclenche le processus d'envoi ; EXPRESS effectue l'envoi pendant la requête.
isHtml	boolean	Oui	Indique si body contient du HTML. Le HTML est nettoyé avant enregistrement.
sender	object	Oui hors brouillon	Expéditeur ; email est obligatoire hors brouillon et entityId est facultatif.
recipients	array	Oui hors brouillon	Destinataires. Un élément peut être une adresse textuelle ou un objet identifiant une adresse, un contact ou un utilisateur.
cc	array	Non	Destinataires en copie.
cci	array	Non	Destinataires en copie cachée.
object	string	Non	Objet du courriel, de 1 à 255 caractères lorsqu'il est renseigné.
body	string	Non	Corps du courriel.
document	object	Non	Courrier et éléments joints au courriel.
document.id	integer	Oui si document est renseigné	Identifiant du courrier.
document.isLinked	boolean	Oui si document est renseigné	Indique si le courrier est joint.
document.original	boolean	Oui si document est renseigné	Indique si le fichier original du courrier est utilisé.
document.attachments	array d'object	Non	Pièces jointes, chacune avec id entier et original booléen.
document.notes	array d'integer	Non	Identifiants des notes jointes.

{
  "document": {
    "id": 124,
    "isLinked": false,
    "original": false,
    "attachments": [],
    "notes": []
  },
  "sender": {
    "email": "service@example.org"
  },
  "recipients": [
    {
      "email": "destinataire@example.org",
      "type": "email"
    }
  ],
  "cc": [],
  "cci": [],
  "object": "Réponse à votre courrier",
  "body": "Bonjour",
  "isHtml": false,
  "status": "DRAFT"
}

Retours et erreurs

Code HTTP	Type	Description	Exemple
200	object	Courriel créé.	{"id":42}
400	object	status est absent, vide ou non textuel.	{"errors":"Data status is not a string or empty"}
400	object	L'expéditeur requis est absent.	{"errors":"Data sender email is not set"}
400	object	Les destinataires requis sont absents.	{"errors":"Data recipients is not an array or empty"}
400	object	isHtml n'est pas un booléen.	{"errors":"Data isHtml is not a boolean or empty"}
400	object	L'objet est invalide ou dépasse 255 caractères.	{"errors":"Data object is not a string or is more than 255 characters"}
400	object	L'adresse ou l'entité de l'expéditeur n'est pas autorisée.	{"errors":"Data sender email is not allowed"}
400	object	La structure de document est invalide.	{"errors":"Data document errors"}
400	object	L'empreinte du courrier ne correspond pas.	{"errors":"Document has fingerprints which do not match"}
400	object	La configuration du serveur de courriel est absente.	{"errors":"Configuration is missing"}
403	object	Le privilège sendmail est absent.	{"errors":"Service forbidden"}
403	object	Le courrier est hors périmètre.	{"errors":"Document out of perimeter"}
403	object	Une pièce jointe ou une note est hors périmètre.	{"errors":"Attachment out of perimeter"}

Les validateurs distinguent également les erreurs de structure Data document[attachments] is not an array, Data document[attachments] errors, Data document[notes] is not an array et Data document[notes] errors. Une note non visible renvoie Note out of perimeter avec le code 403.

Consulter un courriel

Cette action retourne un courriel lié à un courrier.

GET /rest/emails/{id}

Authentification, privilège et périmètre

L'authentification REST est obligatoire. Aucun privilège fonctionnel supplémentaire n'est contrôlé. Le courrier lié doit appartenir au périmètre de l'utilisateur.

Le privilège view_confidential_contact_information détermine si les adresses confidentielles des contacts sont présentes dans la réponse.

Paramètre d'URL

Valeur	Type	Obligatoire	Description
id	integer	Oui	Identifiant du courriel.

Retours

Code HTTP	Type	Description	Exemple
200	object	Courriel et document associé.	Voir l'exemple.
403	object	Le courriel n'existe pas.	{"errors":"Email not found"}
403	object	Le courriel n'est pas lié à un courrier.	{"errors":"Email not linked to a resource"}
403	object	Le courrier associé est hors périmètre.	{"errors":"Document out of perimeter"}

{
  "id": 42,
  "sender": {
    "email": "service@example.org",
    "label": null
  },
  "recipients": [
    {
      "email": "destinataire@example.org",
      "type": "email"
    }
  ],
  "cc": [],
  "cci": [],
  "userId": 19,
  "object": "Réponse à votre courrier",
  "body": "Bonjour",
  "isHtml": false,
  "status": "DRAFT",
  "creationDate": "2026-08-06 10:30:00",
  "sendDate": null,
  "document": {
    "id": 124,
    "isLinked": false,
    "original": false
  }
}

Lister les courriels d'un courrier

Cette action retourne les courriels associés à un courrier. Les brouillons d'un autre utilisateur ne sont pas retournés.

GET /rest/resources/{resId}/emails

Authentification, privilège et périmètre

L'authentification REST est obligatoire. Aucun privilège fonctionnel supplémentaire n'est contrôlé. Le courrier doit appartenir au périmètre de l'utilisateur. Le privilège view_confidential_contact_information régit l'affichage des adresses confidentielles.

Paramètres

Emplacement	Valeur	Type	Obligatoire	Description
URL	resId	integer	Oui	Identifiant du courrier.
Query string	limit	integer	Non	Nombre maximal de courriels retournés.
Query string	type	string	Non	ar filtre les accusés de réception, m2m les échanges machine à machine et email les autres courriels. Une autre valeur n'ajoute aucun filtre de type.

Retours et erreurs

Code HTTP	Type	Description	Exemple
200	object	Tableau emails. Chaque élément reprend les données enregistrées du courriel.	{"emails":[]}
400	object	limit n'est pas un entier.	{"errors":"Query limit is not an int value"}
400	object	type n'est pas une chaîne.	{"errors":"Query type is not a string value"}
403	object	resId n'est pas un entier ou le courrier est hors périmètre.	{"errors":"Document out of perimeter"}

Modifier un courriel

Cette action remplace les données d'un courriel appartenant à l'utilisateur connecté. La valeur de status détermine si le courriel reste en brouillon ou entre dans le processus d'envoi.

PUT /rest/emails/{id}

Authentification, privilège et périmètre

L'authentification REST est obligatoire. Aucun privilège fonctionnel supplémentaire n'est contrôlé. Le courriel doit appartenir à l'utilisateur connecté.

Lorsqu'un courrier est référencé dans document, il doit appartenir au périmètre de l'utilisateur. Les pièces jointes doivent appartenir à ce courrier et les notes doivent être visibles par l'utilisateur. L'adresse de l'expéditeur doit faire partie des adresses autorisées pour l'utilisateur. Une configuration de serveur de courriel doit être présente.

Paramètre d'URL

Valeur	Type	Obligatoire	Description
id	integer	Oui	Identifiant du courriel.

Body JSON

Valeur	Type	Obligatoire	Description
status	string	Oui	Valeurs acceptées : DRAFT, WAITING ou EXPRESS. DRAFT conserve le brouillon ; une autre valeur place le courriel au statut WAITING et déclenche le processus d'envoi.
isHtml	boolean	Oui	Indique si body contient du HTML. Le HTML est nettoyé avant enregistrement.
sender	object	Oui hors brouillon	Expéditeur ; email est obligatoire hors brouillon et entityId est facultatif.
recipients	array	Oui hors brouillon	Destinataires. Un élément peut être une adresse textuelle ou un objet identifiant une adresse, un contact, un utilisateur ou une entité.
cc	array	Non	Destinataires en copie.
cci	array	Non	Destinataires en copie cachée.
object	string	Non	Objet du courriel, de 1 à 255 caractères lorsqu'il est renseigné.
body	string	Non	Corps du courriel.
document	object	Non	Courrier et éléments joints au courriel.
document.id	integer	Oui si document est renseigné	Identifiant du courrier.
document.isLinked	boolean	Oui si document est renseigné	Indique si le courrier est joint.
document.original	boolean	Oui si document est renseigné	Indique si le fichier original du courrier est utilisé.
document.attachments	array d'object	Non	Pièces jointes, chacune avec id entier et original booléen.
document.notes	array d'integer	Non	Identifiants des notes jointes.

Cette route applique une mise à jour complète : les propriétés facultatives omises sont remplacées par leur valeur vide ou par null.

{
  "document": {
    "id": 124,
    "isLinked": false,
    "original": false,
    "attachments": [],
    "notes": []
  },
  "sender": {
    "email": "service@example.org"
  },
  "recipients": [
    {
      "email": "destinataire@example.org",
      "type": "email"
    }
  ],
  "cc": [],
  "cci": [],
  "object": "Réponse mise à jour",
  "body": "Bonjour",
  "isHtml": false,
  "status": "DRAFT"
}

Retours et erreurs

Code HTTP	Type	Description	Exemple
204	aucun	Courriel modifié. Aucun contenu n'est retourné.
400	object	id est vide ou n'est pas un entier.	{"errors":"Param id is not an integer or empty"}
400	object	Le courriel n'existe pas.	{"errors":"Email does not exist"}
400	object	status est absent, vide, non textuel ou non autorisé.	{"errors":"Data status is not allowed"}
400	object	L'expéditeur ou les destinataires requis sont absents.	{"errors":"Data recipients is not an array or empty"}
400	object	isHtml, l'objet, le corps ou un destinataire est invalide.	{"errors":"Data isHtml is not a boolean or empty"}
400	object	L'adresse ou l'entité de l'expéditeur n'est pas autorisée.	{"errors":"Data sender email is not allowed"}
400	object	La structure de document est invalide.	{"errors":"Data document errors"}
400	object	L'empreinte du courrier ne correspond pas.	{"errors":"Document has fingerprints which do not match"}
400	object	La configuration du serveur de courriel est absente.	{"errors":"Configuration is missing"}
403	object	Le courriel appartient à un autre utilisateur.	{"errors":"Email out of perimeter"}
403	object	Le courrier est hors périmètre.	{"errors":"Document out of perimeter"}
403	object	Une pièce jointe ou une note est hors périmètre.	{"errors":"Attachment out of perimeter"}

Les validateurs distinguent également les erreurs de structure Data document[attachments] is not an array, Data document[attachments] errors, Data document[notes] is not an array et Data document[notes] errors. Une note non visible renvoie Note out of perimeter avec le code 403.

Supprimer son courriel

Cette action supprime un courriel créé par l'utilisateur connecté.

DELETE /rest/emails/{id}

Authentification, privilège et périmètre

L'authentification REST est obligatoire. Aucun privilège fonctionnel supplémentaire n'est contrôlé. Le courriel doit appartenir à l'utilisateur connecté.

Paramètre d'URL

Valeur	Type	Obligatoire	Description
id	integer	Oui	Identifiant du courriel.

Retours et erreurs

Code HTTP	Type	Description	Exemple
204	aucun	Courriel supprimé.
400	object	Le courriel n'existe pas.	{"errors":"Email does not exist"}
403	object	Le courriel appartient à un autre utilisateur.	{"errors":"Email out of perimeter"}