Transactionele e-mails koppelen via de API voor developers

Dit artikel is voor de developer die de koppeling bouwt. De shop maakt de e-mails aan in Reloadify en levert de e-mail-ID's en een API-sleutel aan. Lees voor die kant Transactionele e-mails versturen via de API.

De volledige API-documentatie vind je op api.reloadify.com/api-docs.

Aanmelden

Vraag een token aan met de client ID en client secret van de shop:

POST https://api.reloadify.com/oauth/token grant_type=client_credentials, client_id, client_secret

Het token is twee uur geldig. Vraag daarna een nieuw token aan.

Een e-mail versturen

POST https://api.reloadify.com/api/v2/languages/{taal}/transactional_emails/{id}/send

[Check: {taal} of {language_id}, en welke waarde hoort hier?]

Reloadify zoekt de klant op e-mailadres. Bestaat de klant nog niet, dan maakt Reloadify een profiel aan. Bestaat de klant al, dan werkt Reloadify het profiel bij met de gegevens uit profile.

Velden in profile:

Verplicht: email.
Optioneel: id (eigen klantnummer), voornaam, achternaam, tags, adres en custom_attributes.

custom_attributes is een lijst met name en één waarde: string_value, integer_value, date_value, datetime_value of boolean_value. De name moet bestaan onder Instellingen > Custom velden. Onbekende velden negeert Reloadify.

Het veld active wordt genegeerd. Een inactief profiel activeer je niet via dit endpoint.

Bestelgegevens meesturen met data

Stuur gegevens die bij één bestelling horen mee in data, niet in custom_attributes. Custom velden staan op het klantprofiel en de mail wordt kort na het verzoek gerenderd. Plaatst een klant twee bestellingen kort na elkaar, dan kan het tweede verzoek de gegevens van het eerste overschrijven.

Houd deze verdeling aan:

profile: gegevens over de persoon, zoals e-mailadres en naam.
data: alles van deze ene bestelling, zoals ordernummer, producten en afleveradres.

De indeling van data is vrij, met geneste objecten en lijsten. Reloadify slaat data niet op het klantprofiel op. De gegevens blijven behouden bij uitstel of een nieuwe poging.

Limieten voor data:

maximaal 64 KB JSON;
maximaal 20 niveaus diep;
geen null-tekens of ongeldige UTF-8.

Een verzoek zonder data werkt zoals voorheen.

Bestelgegevens tonen in het ontwerp

In de editor staat data beschikbaar als {{ data.* }}, bijvoorbeeld {{ data.order.number }}. Geef de shop door welke namen bij jullie indeling horen. De shop vindt de uitleg over het plaatsen van merge-tags in Transactionele e-mails versturen via de API.

Let op: Reloadify escapet waarden in data niet automatisch. Stuur je tekst mee die een klant zelf heeft ingevuld, zoals een adres of opmerking? Laat de shop dan | escape gebruiken, of plaats de merge-tags zelf.

Voorbeeld van het verzoek

curl -X POST "https://api.reloadify.com/api/v2/languages/Nederlands/transactional_emails/1755/send" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "profile": {
    "email": "[email protected]",
    "first_name": "Anna"
  },
  "data": {
    "order": {
      "number": "WP-48213",
      "total": "49.95",
      "lines": [
        { "name": "Band", "quantity": 1, "price": "49.95" }
      ]
    },
    "shipping": { "street": "Voorbeeldstraat 1", "city": "Enschede" }
  }
}'

Antwoord en limieten

Bij succes geeft de API HTTP 202 terug met een reference en status: "queued". De mail gaat binnen enkele seconden de deur uit. Een bounce na verzending komt niet terug via de API, maar is zichtbaar op het klantprofiel.

De API verwerkt maximaal 60 verzoeken per minuut per shop. Daarboven volgt HTTP 429. Wacht kort en verstuur het verzoek opnieuw.

Foutmeldingen

Bij een foutmelding zet Reloadify niets in de wachtrij.

Melding	Betekenis	Oplossing
Transactional email has no subject configured	Geen onderwerp	Laat de shop een onderwerp invullen bij de e-mail.
Transactional email has no content designed yet	Geen inhoud	Laat de shop de mail ontwerpen en opslaan.
Transactional email template contains invalid Liquid	Fout in een merge-tag	Controleer de merge-tags in de editor.
Could not find transactional email with id	Verkeerd ID	Controleer het ID in de adresbalk.
Shop is not verified for sending yet	Shop niet geverifieerd	Laat de shop contact opnemen met support.
Shop has no active subscription	Geen actief abonnement	Laat de shop het abonnement controleren.
Shop has no sender name and email configured	Geen afzender ingesteld	Laat de shop de afzender instellen bij de verzendinstellingen.
Profile is inactive or email filtered	Klant kan geen mail ontvangen	Controleer het e-mailadres van de klant.
Per-send data is not enabled for this shop (HTTP 403)	Bestelgegevens per e-mail staan niet aan	Laat de shop support vragen de functie aan te zetten.
HTTP 422 bij data	Gegevens te groot, te diep genest of ongeldige tekens	Houd data onder 64 KB en 20 niveaus, zonder ongeldige tekens.
HTTP 429	Meer dan 60 verzoeken per minuut	Wacht kort en verstuur opnieuw.