Envoyer un email

Composer un email à partir d'un modèle, l'envoyer depuis un compte email de l'organisation, puis suivre son statut.

3 min de lecture Mise à jour le 11 novembre 2026

1Le modèle et le compte d'envoi

GET https://staging-api.docage.com/Mails/TemplatesIdAndName
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl "https://staging-api.docage.com/Mails/TemplatesIdAndName" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Get, "https://staging-api.docage.com/Mails/TemplatesIdAndName");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Mails/TemplatesIdAndName", {
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

Choisissez un modèle d'email ordinaire (DefaultMailType à 0 : les autres servent les notifications des parcours et des formulaires). Lisez-le (GET https://staging-api.docage.com/Mails/{id}) pour relever l'identifiant convivial de ses destinataires (MailRecipients[].FriendlyName) et de ses pièces jointes (MailFiles[].FriendlyName).

Les comptes email de l'organisation : GET https://staging-api.docage.com/Mailboxes. Gardez l'identifiant de celui qui enverra (MailboxId).

2Composer l'email, sans l'envoyer

cURL

curl -X POST "https://staging-api.docage.com/Mails/CreateFullMail?sendMail=false" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -F "TemplateId=00000000-0000-4000-8000-000000000501" \
  -F "Client=00000000-0000-4000-8000-000000000201" \
  -F 'Mail={"MailboxId":"00000000-0000-4000-8000-000000000502","Subject":"Votre devis, Camille"}' \
  -F "Devis=@devis-atelier-lumiere.pdf;type=application/pdf"

TemplateId : le modèle ; Mail (facultatif) : ce qui change, en JSON — le compte d'envoi, l'objet…
Un destinataire, sous l'identifiant convivial du destinataire du modèle (Client) : l'identifiant d'un contact ou d'un utilisateur, ou un contact en JSON.
Une pièce jointe, sous l'identifiant convivial d'une pièce jointe du modèle (Devis) : un fichier.

Sans modèle, Mail porte l'email entier : son objet, son corps (BodyType 1 et BodyHtml), son compte d'envoi et ses destinataires (MailRecipients : RecipientType 0 à, 1 copie, 2 copie cachée ; PersonType 1 contact, 0 utilisateur, avec ContactId ou DocageUserId).

La réponse est l'email enregistré, en brouillon : gardez son Id.

3L'envoyer

POST https://staging-api.docage.com/Mails/Send/00000000-0000-4000-8000-000000000503
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…

curl -X POST "https://staging-api.docage.com/Mails/Send/00000000-0000-4000-8000-000000000503" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…"

using HttpClient client = new();
using HttpRequestMessage request = new(HttpMethod.Post, "https://staging-api.docage.com/Mails/Send/00000000-0000-4000-8000-000000000503");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Mails/Send/00000000-0000-4000-8000-000000000503", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`
  }
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

200 : l'email part. Les champs de fusion ({{Recipient_FirstName}}…) sont remplis à l'envoi, pour chaque destinataire ; l'objet et le corps sont traduits dans la langue du destinataire principal quand elle diffère de celle de l'email.

Les refus : 409 pour un email déjà parti, sans destinataire principal, ou dont un destinataire n'a pas d'adresse ; 404 pour un email introuvable, ou que vous ne voyez pas ; 403 pour un email que vous voyez sans pouvoir le modifier — envoyer un brouillon, c'est le modifier ; 400 pour un envoi qui échoue, avec son motif.

4Suivre son statut

GET https://staging-api.docage.com/Mails/{id} : Status, sa date (StatusDate), ses ouvertures (FirstOpenedDate, OpenCount) et ses clics (FirstClickedDate, ClickCount).

`Status`	Statut
`0`	Brouillon
`1`	Programmé
`2`	Envoyé
`3`	Remis
`4`	Ouvert
`5`	Lien ouvert
`-1`	Différé
`-2`	Rejet temporaire
`-3`	Rejet définitif
`-4`	Email invalide
`-5`	Spam
`-6`	Bloqué
`-7`	Désabonné
`-8`	En attente du relais
`-100`	Erreur

Le webhook de l'événement 30, « changement de statut de l'email », vous prévient sans relire.

Les pièges

sendMail est vrai d'office : sans sendMail=false, la création envoie aussitôt, et un envoi refusé laisse l'email enregistré sans vous en donner l'identifiant. Composez, puis envoyez.
Un contact en JSON met à jour un contact existant : celui que désigne son Id, sinon celui du destinataire du modèle, aussitôt ; sans l'un ni l'autre, un contact est créé. Pour une personne connue, sans rien changer à sa fiche, envoyez l'identifiant de son contact.
Un email commercial (IsMarketing) part d'un compte email de l'organisation, jamais d'un compte de la plateforme, vers un seul destinataire ; il porte un lien de désabonnement, et ne part pas vers une adresse désabonnée (statut -7).
L'ouverture d'un email n'est pas comptée pendant la première minute qui suit son envoi.