API de la messagerie des boutiques

Pour les emails envoyés, l’objet tracking fournit les ouvertures et clics détectés, leurs premières et dernières dates UTC et l’état du destinataire dans le flux Postmark. Ces indicateurs restent distincts de la distribution et ne prouvent pas une lecture humaine.

Tous les endpoints utilisent shopID et key, la clé API habituelle de la boutique. Ses webservices doivent être activés. Chaque requête accède uniquement aux messages, dossiers, pièces jointes et clients de cette boutique.

Les GET utilisent les paramètres de l’URL. Les POST acceptent application/json, application/x-www-form-urlencoded ou multipart/form-data. shopID et key peuvent être dans l’URL ou dans le corps POST ; des valeurs contradictoires sont refusées. Les cookies de connexion ne servent pas à authentifier cette API. Utilisez HTTPS.

Appliquez les migrations de messagerie existantes avant la mise en service. Aucun endpoint supplémentaire d’attribution d’adresse et aucune nouvelle migration SQL ne sont nécessaires.

Endpoints disponibles

Consultation et filtres

• box : inbox par défaut, ou sent pour les emails envoyés. Les identifiants des deux boîtes sont distincts : fournissez toujours la boîte avec un identifiant.
• id, message_id, folder_id : identifiants entiers positifs ; folder_id=0 désigne la boîte principale sans dossier.
• page, per_page : page à partir de 1 ; 25 messages par défaut, ou 10 pour les réponses ; maximum 100 par page. Le décalage total est limité à un million de lignes. Une page au-delà du résultat est vide, sans revenir à la dernière page.
• search : recherche dans l’objet et l’expéditeur pour les reçus, dans l’objet et le destinataire pour les envoyés ; maximum 200 octets. Les caractères % et _ sont recherchés littéralement.
• folder_id : all ou absent pour tous les reçus ; 0 pour la boîte principale ; identifiant positif pour un dossier. Ce filtre concerne uniquement les reçus.
• read, replied : 0 ou 1, ou booléens JSON, uniquement pour les reçus. Omettre un filtre pour inclure les deux états.
• status : sending | sent | delivered | failed | bounced | spam_complaint. Concerne uniquement les envoyés et les listes de réponses.
• from, to : date YYYY-MM-DD ou horodatage UTC YYYY-MM-DDTHH:MM:SSZ. La borne from est incluse ; la borne to est exclue pour un horodatage et couvre toute la journée pour une date. Les filtres portent sur received_at pour les reçus, created_at pour les envoyés.

Les listes retournent box, messages, total, page, per_page, pages et has_more. Les dates des emails sont en UTC au format YYYY-MM-DD HH:MM:SS. Les valeurs absentes restent null. Les états techniques restent stables ; les libellés et messages humains sont traduits dans la langue de la boutique avec showTradRAW.

getMailbox.php retourne mailbox.address, mailbox.sender_address, mailbox.sending_enabled, les compteurs all et inbox, puis sent.total et sent.statuses. address et sender_address utilisent la même adresse de boutique en @shop.kash.click, en production comme en développement.

getMailboxMessage.php retourne message avec text_body, html_body, attachments et les états. Chaque pièce jointe indique id, name, content_length, content_type, available et download_url. Ajoutez shopID et key à cette URL pour télécharger le fichier. Certaines pièces jointes envoyées avant l’activation de l’archivage peuvent être indiquées comme indisponibles.

Le HTML est retourné tel qu’enregistré. Pour l’afficher, utilisez un cadre isolé avec sandbox et une politique CSP, comme la page de messagerie du logiciel. Le téléchargement renvoie application/octet-stream avec Content-Disposition: attachment. Aucun jeton de suivi privé ni clé API n’est retourné.

Envoi, erreurs de distribution et répétition des requêtes

• sendMailboxMessage.php : fournissez soit to, une adresse email unique valide, soit customer_id, un client de cette boutique dont l’email est relu en base. Les deux à la fois sont refusés. subject est obligatoire, sur une ligne, de 1 à 998 octets. body est un texte UTF-8 non vide, de 100 000 octets maximum ; ses retours à la ligne sont convertis en HTML.
• replyMailboxMessage.php : fournissez message_id et body. L’objet est repris avec Re: et le destinataire vient du Reply-To valide du message, sinon de son expéditeur. Une réponse acceptée marque automatiquement l’email reçu comme répondu. Une réponse échouée ne le marque pas.
• request_key : obligatoire pour les deux envois ; 32 à 64 caractères hexadécimaux minuscules, par exemple une valeur aléatoire de 16 octets. Générez une nouvelle clé pour chaque nouveau message. Après une interruption réseau, réutilisez exactement la même requête et la même clé : elle retrouve la tentative initiale sans renvoyer l’email, même si celle-ci a échoué. Pour une nouvelle tentative volontaire après un échec, créez une nouvelle clé. La clé conserve le premier corps soumis ; modifier le corps avec la même clé ne crée pas un nouvel envoi.

La réponse d’envoi contient message, accepted, duplicate et simulated. success=true signifie que la requête a été traitée. accepted=true signifie que le transport a accepté l’email ; cela ne confirme pas sa distribution. Une tentative refusée mais archivée retourne success=true, accepted=false et son message.status=failed avec error_code et error_reason. Consultez ensuite le message pour connaître les événements Postmark. delivery_confirmed vaut true uniquement pour l’état delivered. simulated=true correspond à une boutique de test interceptée avant l’envoi, sans email réellement envoyé.

Une réponse du client est toujours enregistrée comme un nouvel email reçu. getMailboxReplies.php liste les tentatives de réponse sortantes liées au message original, sans fusionner les nouveaux emails entrants.

Dossiers, états et clients

Les dossiers sont propres à la boutique. Le nom contient de 1 à 80 caractères ; espaces superflus normalisés, unicité sans distinction de casse ni d’accent. editMailboxMessage.php accepte read et/ou replied ; les deux modifications sont atomiques. Mettre replied à 0 retire le marquage, mais conserve l’historique des réponses.

searchMailboxCustomers.php accepte search de 2 à 100 caractères. Il retourne au maximum 20 customers avec id, label et email, ainsi que has_more et minimum_length=2. Si has_more vaut true, précisez la recherche ; il n’y a pas de pagination de tout le carnet clients.

getMailboxCustomer.php accepte message_id avec box, ou email. Le message est prioritaire si les deux sont fournis. status vaut matched, ambiguous ou none. matches contient uniquement id, nom, prenom et email. Pour un client unique, customer comprend coordonnées, création, nombrecommandes, totalpaiement, pointsfidelite, avoir et notes ; latest_order résume la dernière commande validée, y compris les archives si elles sont activées, avec id, idinterne, datecreation, prixfinal et archive. display_order résume la commande citée dans le message ou, à défaut, la dernière commande validée. display_order_source vaut message, latest ou null. La détection utilise les références #numéro (avec le préfixe de la boutique) dans l’objet et le corps. Les pièces jointes Facture numéro.pdf et Invoice numéro.pdf désignent idinterne ; Devis ID.pdf et Quote ID.pdf désignent la clé primaire id, sans préfixe. Ces recherches sont limitées aux commandes du client de cette boutique, y compris les devis non encore validés. currency contient l’identifiant et le symbole de devise de la boutique. preferred donne les jours favoris, leur pourcentage et la taille de l’échantillon ; customer.preferred_days détaille les sept jours (0=dimanche à 6=samedi). Les mots de passe clients ne sont jamais retournés.

Exemples JavaScript

const credentials = { shopID: "[SHOPID]", key: "[APIKEY]" };const url = (endpoint, params = {}) => "/workers/" + endpoint + ".php?" + new URLSearchParams({ ...credentials, ...params });const mailbox = await fetch(url("getMailbox")).then(r => r.json());const unread = await fetch(url("getMailboxMessages", { box: "inbox", read: 0, page: 1, per_page: 25})).then(r => r.json());// Conserver cette clé et ces paramètres en cas de reprise après un échec réseau.const bytes = crypto.getRandomValues(new Uint8Array(16));const request_key = Array.from(bytes, b => b.toString(16).padStart(2, "0")).join("");const sent = await fetch(url("sendMailboxMessage"), { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({  customer_id: 123, subject: "Votre commande",  body: "Bonjour,\nVotre commande est prête.", request_key })}).then(r => r.json());const read = await fetch(url("editMailboxMessage"), { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ message_id: 456, read: true })}).then(r => r.json());

Erreurs HTTP

Les erreurs JSON retournent success=false, result traduit et error_code stable. HTTP 400 : paramètres invalides, incohérents ou JSON mal formé ; 403 : clé/boutique invalide ou webservices désactivés ; 404 : ressource absente dans cette boutique ; 405 : méthode incorrecte, avec en-tête Allow ; 413 : corps JSON supérieur à 150 000 octets ; 415 : format non pris en charge ; 503 : migration manquante, envoi désactivé ou indisponibilité. Les erreurs SQL et identifiants techniques privés ne sont pas exposés.

{"success":false,"result":"Message introuvable dans cette boutique.","error_code":"not_found"}

Les quinze endpoints sont également décrits dans le schéma OpenAPI à la racine du site. /openapi.json