REST API-referens
REST API för e-postmallar, avsändare, historik och statistik i Shopify Flow-appen Workflow Transactional Email, med slutpunkter och åtkomstnivåer.
Alla sökvägar är relativa till https://shopify.workflow-transactional-email.app. Varje slutpunkt utom index kräver Authorization: Bearer fak_... - se Autentisering och API-nycklar.
Svaren är i JSON-format. Felmeddelandena har samma struktur genomgående:
{ "error": "Invalid or missing API key" }Index och identitet
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1 |
ingen | API-index. Bekräftar att API:et är i drift och visar aktuell version |
| HÄMTA | /api/v1/me |
läs | Kontrollera om en nyckel fungerar och se vilken åtkomstnivå den har |
Indexet kräver ingen nyckel, så det är en säker hälsokontroll att rikta en monitor mot.
E-postmallar
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/email-templates |
läs | Visa e-postmallar. q söker efter namn, ämne och beskrivning; category=transactional eller category=marketing visar en viss typ av e-post |
| INLÄGG | /api/v1/email-templates |
skriva | Skapa en layout |
| HÄMTA | /api/v1/email-templates/:id |
läs | En layout med sin design och sina bilagor, sina sidfotstexter och listan över språk |
| PUT / PATCH | /api/v1/email-templates/:id |
skriva | Ändra en layout. Endast de fält du skickar ändras |
| RADERA | /api/v1/email-templates/:id |
skriva | Ta bort en layout tillsammans med dess översättningar och versioner |
| HÄMTA | /api/v1/layout-schema |
läs | Så här skriver du en layout: designformatet, standardinställningarna för varje block, vilka Liquid-koder du kan använda, begränsningar och ett exempel |
Listan accepterar page (standardvärde 1), limit (standardvärde 25, max 100) och q, som söker efter namn, ämne och beskrivning. Det finns inget filter efter typ via API:et; läs istället category i respektive layout.
En layout innehåller följande fält:
| Fält | Anmärkningar |
|---|---|
name, description |
Namn krävs, högst 200 tecken; beskrivning högst 2000 |
bodyType |
visual (standard) eller text. Kan inte ändras efter att den har skapats |
defaultLocale |
Språket för layoutens eget innehåll, en om inget annat anges |
category |
transactional (standard) eller marketing. Se nedan |
subject, previewText |
Flytande vätska tillåten. Ämne krävs |
bodyDesign |
Visuella layouter: { blocks, global?, header?, footer?, testVariables? }. Skicka den fullständiga designen när du ändrar den; HTML-elementet body-renderas utifrån den |
body |
Textlayouter: HTML-kroppen |
attachments |
Textformat: [{ filename, fileKey, sendAsLink? }] för uppladdade filer (se filerna nedan) eller [{ filename, url }] för en fil som hämtas via https när e-postmeddelandet skickas |
marketingTexts |
Fottexterna i en marknadsföringslayout, eller null. Se nedan |
Liquid-kod i ämnesraden, förhandsgranskningstexten, brödtexten och varje textblock måste analyseras, och varje fileKey måste tillhöra din butik, annars avvisas skrivningen med ett 400-fel där fältet anges. Läs GET /api/v1/layout-schema innan du skapar en visuell design: den genereras av själva byggverktyget, så den kan inte avvika.
Varje skrivning via detta API sparas i layoutens versionshistorik, precis som när man sparar i appen.
Layouter för transaktioner och marknadsföring
category anger vad en layout är avsedd för. En transaktionslayout skickas till alla mottagare utan ändringar. En marknadsföringslayout hoppar över mottagare som har avslutat prenumerationen (ett steg där meddelandet ”Alla mottagare i fältet Till har avslutat prenumerationen” inte skickas och visas som SKIPPED i historiken), skickas ut som ett meddelande per mottagare i fältet Till med en egen länk för att avsluta prenumerationen (högst 20 per steg) och avslutas med meningen om att avsluta prenumerationen samt dina företagsuppgifter. {{ unsubscribe_url }} och {{ unsubscribe_link }} - placera länken själv; i transaktionslayouter är båda tomma. Handlarsidan av detta finns i Marknadsföringsmejl och avregistreringar.
marketingTexts är den text i sidfoten som en marknadsföringslayout använder istället för de butiksövergripande texterna från Inställningar:
{
"marketingTexts": {
"unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
"unsubscribeLinkLabel": "Unsubscribe",
"companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
}
}Alla fält är valfria. Ett ifyllt fält ersätter inställningstexten för det fältet; de övriga fälten förblir oförändrade. null (standardvärdet) innebär att texterna under ”Inställningar” för e-postens språk används. Begränsningar: unsubscribeText och companyDetails 2000 tecken, unsubscribeLinkLabel 100. Ett unsubscribeText måste innehålla {{ unsubscribe_link }} eller {{ unsubscribe_url }}, annars avvisas inmatningen. Fältet sparas för alla layouter men skickas endast med marknadsföringslayouter.
Det går alltid att ta bort en layout. Om det fortfarande finns Shopify Flow-steg som hänvisar till den, innehåller svaret en warning-varning som anger hur många; dessa steg misslyckas tills de använder en annan layout.
Översättningar
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/email-templates/:id/translations |
läs | Varje språk i en layout med sitt innehåll |
| HÄMTA | /api/v1/email-templates/:id/translations/:locale |
läs | Ett språk |
| PUT | /api/v1/email-templates/:id/translations/:locale |
skriva | Skapa eller ersätt ett språk |
| RADERA | /api/v1/email-templates/:id/translations/:locale |
skriva | Ta bort ett språk. Vid detta fall återgår man till standardlayouten |
| INLÄGG | /api/v1/email-templates/:id/translations/:locale/promote |
skriva | Ange det språket som layoutens huvudspråk |
:locale är en språkkod, till exempel de, fr eller pt-br; storlekar på bokstäver och avgränsare spelar ingen roll. Upp till 30 språk per layout. Fältet ”Språk” i Shopify Flow-steget väljer ett språk vid sändningstillfället: först den exakta språkinställningen, sedan basspråket, därefter en regional variant och i övriga fall själva layouten.
Ett PUT-anrop tar med hela det översatta innehållet: subject (obligatoriskt), previewText och bodyDesign (visuellt) eller body (text). Lämna Liquid-taggar och URL:er oförändrade. Två fält är specifika för en översättning:
| Fält | Textlayouter | Betydelse |
|---|---|---|
attachments |
ja | En lista (samma form som layoutens) = det här språkets egna bilagor, [] = inga i det här språket. null = skicka layoutens bilagor. Utelämnat = behåll det aktuella valet; ett nytt språk använder layoutens. Visuella layouter har sina bilagor som block i varje språks bodyDesign och avvisar detta fält |
marketingTexts |
någon | Texterna i sidfoten för detta språk läggs ovanpå layoutens, fält för fält. null = layoutens. Utelämnat = behåll det aktuella valet |
En översättning returneras med samma två fält: attachments är null, medan den skickar layoutens, och marketingTexts är null, medan den använder layoutens.
promote byter plats på layouten och översättningen: layouten tar över översättningens innehåll och språkinställning, medan det innehåll som layouten tidigare hade blir översättningen för det språk som den tidigare tillhörde. Bilagor och sidfotstexter byter också plats, så varje språk fortsätter att skicka det som det skickade tidigare. Svaret rapporterar promoted, previousMainLanguage och layouten. Det är en version, så den kan ångras.
Versioner
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/email-templates/:id/versions |
läs | Spara versioner, med de senaste först. Appen sparar de 25 senaste |
| HÄMTA | /api/v1/email-templates/:id/versions/:version |
läs | En fullständig översikt över en version: layout och alla översättningar |
| INLÄGG | /api/v1/email-templates/:id/versions/:version/restore |
skriva | Sätt tillbaka den versionen. Inspelad som en ny version |
| HÄMTA | /api/v1/email-templates/:id/versions/github?page= |
läs | Alla versioner som finns i det anslutna GitHub-arkivet, 20 per sida |
| HÄMTA | /api/v1/email-templates/:id/versions/github/:sha |
läs | Layouten så som den såg ut vid en viss commit |
| INLÄGG | /api/v1/email-templates/:id/versions/github/:sha/restore |
skriva | Återställ en GitHub-version - det fungerar ungefär som att spara |
GitHub-ändpunkterna returnerar felkod 409 när inget arkiv är anslutet på utvecklarsidan. Se Historik över layoutversioner och Spara obegränsad layouthistorik på GitHub.
Avsändare av e-postmeddelanden
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/smtp-configs |
läs | Lista över SMTP-avsändare |
| HÄMTA | /api/v1/senders |
läs | Visa anslutna postlådor (Microsoft 365, Google) |
SMTP-avsändare rapporterar hasUsername och hasPassword istället för själva inloggningsuppgifterna - båda delarna döljs, eftersom ett användarnamn är en lika viktig del av inloggningsuppgifterna som lösenordet. En avsändare förblir identifierbar genom sitt namn, sin värd och sin avsändaradress. Anslutna e-postkonton rapporterar en delvis maskerad adress, till exempel so***@example.com, och aldrig sina inloggningstoken.
Endast läsning. Anslut och redigera avsändare i appen.
Hemligheter
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/secrets |
läs | Lista över hemliga namn och beskrivningar |
Returnerar hasValue, aldrig själva värdet. Det finns ingen API-ändpunkt som hämtar en hemlighet. Skapa och uppdatera hemligheter i appen.
Uppladdade filer
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/files |
läs | Lista över uppladdade logotyper, bilder och bilagor |
| RADERA | /api/v1/files |
skriva | Ta bort en, efter key-värdet i brödtexten |
List tar emot page, limit (max 100) och q för att söka efter filnamn.
Lägg till ?usage=true, så visar varje fil även inUse samt en usedBy-matris med namnen på de layouter och förinställningar som refererar till den. På så sätt kan du med en enda förfrågan se allt som är säkert att rensa bort. Funktionen skannar dina layouter och förinställningar, så den är aktiverad endast om du väljer det - det är inte standardinställningen.
Uppladdning är inte tillgänglig här - lägg till filer via medievalaren i appen.
HTTP-förfrågningar
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/http-requests |
läs | Lista över HTTP-förfrågningar |
| INLÄGG | /api/v1/http-requests |
skriva | Skapa en |
| HÄMTA | /api/v1/http-requests/:id |
läs | Skaffa en |
| PUT / PATCH | /api/v1/http-requests/:id |
skriva | Uppdatering 1 |
| RADERA | /api/v1/http-requests/:id |
skriva | Ta bort en |
| INLÄGG | /api/v1/http-requests/:id/test |
utföra | Kör det mot det verkliga målet |
List tar emot samma parametrar som e-postmallar: page, limit och q.
Mål-url måste vara http:// eller https://. Andra scheman avvisas när du sparar.
Autentiseringsuppgifter som anges direkt i en rubrik eller i brödtexten döljs i varje svar. Värden som refereras till som {{ secrets.KEY }} returneras oförändrade, eftersom själva referensen inte är känslig.
Historia och statistik
Omfattar både e-postutskick och HTTP-förfrågningar.
| Metod | Sökväg | Nivå | Syfte |
|---|---|---|---|
| HÄMTA | /api/v1/history |
läs | Lista över körningar |
| HÄMTA | /api/v1/history/:id |
läs | Hämta en körning med begäran- och svarsdata |
| HÄMTA | /api/v1/stats |
läs | Totalsiffror och framgångsgrad |
Historiken accepterar page, limit (max 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) och actionConfigId för att filtrera fram en enskild layout eller begäran.
SKIPPED är ett marknadsföringsmejl vars mottagare alla hade avslutat sin prenumeration: inget skickades, ingen kvot förbrukades och det räknas inte in i framgångsgraden.
actionType måste vara exakt EMAIL eller HTTP_REQUEST. Ett okänt värde ignoreras istället för att avvisas, vilket innebär att ett skrivfel resulterar i att allt returneras istället för att ett felmeddelande visas.
Stats accepterar days (standardvärde 30, max 365).
Statuskoder
| Kod | Betydelse |
|---|---|
| 200 | Framgång |
| 201 | Skapad |
| 400 | Felaktig begäran eller misslyckad validering. I error anges fältets namn, till exempel subject: required |
| 401 | Saknad, felaktig eller återkallad API-nyckel |
| 403 | Nyckeln är giltig, men dess säkerhetsnivå är för låg för denna slutpunkt |
| 404 | Hittades inte, eller tillhör en annan butik |
| 405 | Fel metod för den här sökvägen |
| 409 | Avvisat eftersom posten fortfarande används (filradering) eller eftersom GitHub inte är anslutet (GitHub-versioner) |
| 429 | Hastighetsbegränsat - se nedan |
| 502 | Begäran kördes, men målet från tredje part misslyckades |
En post som tillhör en annan butik returnerar 404 istället för 403, vilket innebär att API:et aldrig bekräftar att ett id finns någon annanstans.
Begränsningar av antalet förfrågningar
Två separata budgetar, båda per nyckel:
- 300 förfrågningar per 60 sekunder för alla slutpunkter.
- Utöver det ska 60 anrop utföras per timme, som omfattar
POST /api/v1/http-requests/:id/test.
Om något av dessa gränsvärden överskrids returneras 429 tillsammans med ett förklarande error-meddelande. Utförandebudgeten är avsiktligt snäv: en okontrollerad loop som skickar liveförfrågningar till en betalningsleverantör är ett betydligt allvarligare fel än ett långsamt skript.
Budgetarna gäller per nyckel, inte per butik, så en integration kan inte tömma en annan integrations budget.