Claus API: com crear-les i gestionar-les

Una clau API és un codi únic que permet que una altra aplicació (el teu web, el teu CRM, la teva botiga en línia o un desenvolupament propi) es connecti al teu compte de Mailrelay sense fer servir el teu usuari i contrasenya. Amb ella, aquests sistemes poden afegir subscriptors, enviar emails transaccionals o consultar estadístiques de manera automàtica.

Necessitaràs una clau API si vols integrar Mailrelay amb una altra eina, si fas servir un plugin o connector que te la demani, o si el teu equip de desenvolupament treballarà amb l'API de Mailrelay. Les claus API estan disponibles en tots els comptes, inclòs el compte gratuït.

On trobar les claus API

Al teu compte de Mailrelay, ves a Configuració > Claus API. En aquesta secció pots veure les claus que ja existeixen, crear-ne de noves i eliminar les que ja no necessitis.

A la part superior de la pàgina també trobaràs un enllaç a la documentació de l'API, que inclou exemples de codi per facilitar la feina de l'equip de desenvolupament.

Com crear una clau API pas a pas

1. A Configuració > Claus API, fes clic a +Afegeix.
2. S'obrirà la finestra Nova clau API. Al desplegable Usuari, tria l'usuari del compte a qui s'assignarà la clau.
3. Fes clic a Crea Clau API.

4. S'obrirà la finestra Clau API creada amb la teva nova clau. Copia-la amb el botó que apareix al costat i desa-la en un lloc segur. Per seguretat, la clau completa només es mostra aquesta vegada: quan tanquis la finestra no la podràs tornar a veure.

5. Fes clic a Tanca.

La nova clau apareixerà al llistat. Per a cada clau veuràs l'usuari a qui està assignada, els primers caràcters de la clau (perquè la puguis identificar), la data de creació i la data de l'últim ús.

Per què cada clau s'assigna a un usuari

Totes les accions que es fan amb una clau API queden registrades a nom de l'usuari a qui està assignada. Per això és recomanable crear un usuari específic per a cada integració (per exemple, «Integració web» o «CRM»). Així sabràs quin sistema ha fet cada canvi i podràs gestionar cada integració per separat.

Si necessites crear aquest usuari, consulta Com afegir un usuari al compte i Usuaris.

Com eliminar una clau API

Si una integració ja no es fa servir o creus que una clau s'ha vist compromesa, elimina-la des del llistat de Configuració > Claus API amb el botó vermell de la paperera que apareix a la dreta de cada clau. A partir d'aquell moment, qualsevol sistema que continuï fent servir aquesta clau deixarà de tenir accés al teu compte.

La columna d'últim ús t'ajuda a detectar claus que ja no es fan servir i que pots eliminar amb seguretat.

Com comprovar que la clau funciona

Per verificar que la clau és vàlida, pots fer una petició de prova a l'endpoint /ping. La clau s'envia a la capçalera X-AUTH-TOKEN. Si tot és correcte, l'API respondrà amb un codi HTTP 204.

curl -X GET --header 'X-AUTH-TOKEN: LA-TEVA-CLAU-API' 'https://EL-TEU-COMPTE.ipzmarketing.com/api/v1/ping'

Substitueix LA-TEVA-CLAU-API per la clau que has creat i EL-TEU-COMPTE.ipzmarketing.com pel domini del teu compte de Mailrelay, que és el que apareix a la barra del navegador quan entres al teu tauler.

Què pots fer amb l'API de Mailrelay

Amb una clau API pots automatitzar, entre altres coses:

• Afegir, actualitzar o donar de baixa subscriptors, i gestionar-ne els grups i les etiquetes.
• Enviar emails transaccionals, SMS i missatges de WhatsApp.
• Crear i enviar campanyes, i consultar-ne les estadístiques: obertures, clics i baixes.
• Gestionar remitents, camps personalitzats i importacions.
• Rebre avisos automàtics quan passen determinats esdeveniments al teu compte.

Trobaràs tots els endpoints disponibles, amb els seus paràmetres i exemples, a la documentació de l'API. També et poden interessar aquests articles:

• SMS mitjançant la nostra API
• Subscripció d'esdeveniments
• Què són els emails transaccionals? Opcions SMTP i API

Límits d'ús de l'API

L'API té límits de peticions. Els valors vigents, l'error 429 que torna en superar-los i les capçaleres que indiquen quantes peticions queden són a la documentació de l'API, apartat «Rate limiting»

Bones pràctiques de seguretat

Una clau API dona accés complet al teu compte, així que convé protegir-la igual que una contrasenya:

• No la comparteixis per email ni la incloguis al codi públic del teu web.
• Fes servir una clau diferent per a cada integració, assignada al seu propi usuari.
• Desa les claus en un gestor de contrasenyes o a la configuració segura del teu servidor.
• Si creus que una clau s'ha vist compromesa, crea'n una de nova, actualitza les teves integracions i elimina l'anterior.
• Revisa de tant en tant el llistat i elimina les claus que ja no facis servir.

Preguntes freqüents

He perdut la meva clau API. La puc recuperar?

No. Per seguretat, la clau completa només es mostra quan es crea. Crea una clau nova, actualitza-hi les integracions que feien servir l'anterior i elimina la clau antiga del llistat.

Puc fer servir l'API amb el compte gratuït?

Sí. La secció Claus API també està disponible al compte gratuït.

Puc tenir diverses claus API?

Sí. Pots crear diverses claus i assignar cadascuna a un usuari diferent del compte.

On trobo el domini del meu compte?

És el domini que apareix a la barra del navegador quan entres al teu tauler de Mailrelay, per exemple latevaempresa.ipzmarketing.com.