Saltar al contingut principal

Claus API

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, editar-les i eliminar les que ja no necessitis.

Secció Claus API de Mailrelay amb el botó +Afegeix i el llistat de claus

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 pàgina Nova clau API. A Nom, escriu un nom que t'ajudi a identificar la clau, per exemple «CRM» o «Integració web». Aquest camp és obligatori.
  3. Al desplegable Usuari, tria l'usuari del compte a qui s'assignarà la clau.
  4. A Caducitat, tria quan deixarà de funcionar la clau: 7 dies, 14 dies, 1 mes, 3 mesos, 6 mesos, 1 any, Sense caducitat o Personalitzada. A sota del camp veuràs la data en què caduca. Si tries Personalitzada, apareix un camp per triar la data i l'hora en què la clau deixarà de funcionar.
  5. A Adreces IP permeses, pots indicar des de quines adreces es podrà fer servir la clau: una adreça IPv4 o IPv6, o un rang CIDR. Amb +Afegir-ne més s'afegeix un altre camp per a una adreça més, i amb Afegir la meva IP s'omple amb l'adreça IP des de la qual estàs connectat. Si deixes el camp buit, es permeten peticions des de qualsevol IP.

Pàgina Nova clau API amb els camps Nom, Usuari, Caducitat, Adreces IP permeses i Permisos

  1. A Permisos, tria què pot fer la clau:
    • Accés complet: tot el que pot fer el seu usuari, incloses les àrees que s'afegeixin a l'API més endavant.
    • Restringit (recomanat): tries l'accés per a cada àrea: Contactes, Campanyes de correu, Correu transaccional, SMS, SMS transaccional, WhatsApp, WhatsApp transaccional, Ecommerce, Biblioteca de mitjans i Webhooks. Totes les àrees comencen sense accés. A sota de cada àrea s'indica què inclou, i al seu desplegable tries el nivell, per exemple Llegir.
    Per exemple, si una integració només ha d'afegir subscriptors a les llistes de la teva newsletter o de les teves campanyes d'email màrqueting, pots donar-li accés només a Contactes.

Permisos en mode Restringit amb el desplegable d'accés de cada àrea

  1. Fes clic a Crea Clau API.
  2. 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.

Finestra Clau API creada amb l'avís que la clau només es mostrarà una vegada i el botó per copiar-la

  1. Fes clic a Tanca.

La nova clau apareixerà al llistat. Per a cada clau veuràs el nom, l'usuari a qui està assignada, els primers caràcters de la clau (perquè la puguis identificar), l'estat, la data i l'hora de caducitat, les adreces IP permeses 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. A més, la clau només pot fer el que permetin alhora els seus permisos i el seu usuari: encara que triïs Accés complet, mai no podrà fer més del que permet el rol d'aquest usuari.

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. Per veure com es defineixen els permisos de cada usuari, consulta Rols.

Com editar una clau API

Al llistat de Configuració > Claus API, fes clic al botó verd d'edició que apareix a la dreta de la clau. S'obrirà la pàgina Editar clau API, amb els mateixos camps que en crear-la: Nom, Usuari, Caducitat, Adreces IP permeses i Permisos. A Caducitat apareix a més l'opció Mantenir la caducitat actual. Quan acabis, fes clic a Actualitza Clau API per desar els canvis.

Pàgina Editar clau API amb l'opció Mantenir la caducitat actual i el botó Actualitza Clau API

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. El panell et demanarà que confirmis que la vols eliminar. A partir d'aquell moment, qualsevol sistema que continuï fent servir aquesta clau deixarà de tenir accés al teu compte.

Com comprovar que la clau funciona

A la documentació de l'API, apartat «First request», s'explica com fer una primera petició per comprovar que la teva clau és vàlida.

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.

Així pots, per exemple, connectar el teu web o la teva botiga en línia perquè els nous contactes s'afegeixin sols a la llista de la teva newsletter, sense haver-los d'importar a mà abans de cada enviament massiu d'emails.

L'enviament d'emails transaccionals a través de l'API requereix el paquet SMTP + API. La resta d'endpoints de l'API continuen disponibles.

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:

Límits d'ús de l'API

L'API té límits de peticions. Els valors vigents són a la documentació de l'API, apartat «Rate limiting».

Bones pràctiques de seguretat

Una clau API dona accés 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.
  • Si una integració no necessita totes les àrees, tria Restringit a Permisos, que és l'opció que recomana el panell, i dona-li accés només al que faci servir.
  • 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. Per enviar emails transaccionals a través de l'API necessites el paquet SMTP + API.

Puc tenir diverses claus API?

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

Puc limitar el que fa una clau API?

Sí. En crear o editar la clau, a Permisos tria Restringit i dona a cada àrea només l'accés que necessiti. També pots indicar a Adreces IP permeses des de quines adreces es podrà fer servir.

Puc canviar la caducitat d'una clau que ja he creat?

Sí. A la pàgina Editar clau API, tria una opció nova a Caducitat, o deixa Mantenir la caducitat actual si no la vols canviar.

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.

T'ha resultat útil aquest article?

Genial!

Gràcies pels teus comentaris

Sentim que no t'hàgim pogut ajudar

Gràcies pels teus comentaris

Explica'ns com podem millorar aquest article!

Selecciona almenys un dels motius
La verificació de CAPTCHA és obligatòria.

Comentaris enviats

T'agraïm el teu esforç i intentarem arreglar l'article