ajtarragona/mailrelay-client

Client Laravel de la API Rest de MailRelay

v1.0.3 2024-11-19 10:25 UTC

Requires

• php: >=7.0.0
• guzzlehttp/guzzle: ^6.3
• laravel/framework: ^6.0

MIT

• Txomin Medrano Martorell

• laravel
• laravel5

README

Cliente Laravel de la API Rest de MailRelay.

Credits: Ajuntament de Tarragona.

Check the MailRelay API docs here: https://tarragona1.ipzmarketing.com/api-documentation/

• Instalación
• Configuración
• Uso
  • Funciones
    • Senders (Remitentes)
      • getSenders($page=null, $per_page=null)
      • getSender($id)
      • getDefaultSender()
      • createSender($name, $email)
    • Custom Fields
      • getCustomFields($page=null, $per_page=null)
      • getCustomField($id)
      • createCustomField($name, $label, $type="text", $required=false, $default_value="", $options=[])
    • Groups
      • getGroups($page=null, $per_page=null)
      • getGroup($id)
      • createGroup($name, $description=null)
    • Campaigns (Boletines)
      • getCampaigns($page=null, $per_page=null)
      • getCampaign($id)
      • createCampaign($subject, $body, $sender_id, $group_ids=[], $target="groups", $attributes=[])
    • Sent Campaigns (Informes de envio de Boletines)
      • getSentCampaigns($page=null, $per_page=null)
      • getSentCampaign($id)
    • Campaign Folders
      • getCampaignFolders($page=null, $per_page=null)
      • getCampaignFolder($id)
      • createCampaignFolder($name)
    • Imports
      • getImports($page=null, $per_page=null)
      • getImport($id)
      • createImport($filename, $subscribers, $group_ids=[], $callback=null, $ignore=true)
    • Media Files
      • getMediaFiles($page=null, $per_page=null)
      • getMediaFile($id){
      • createMediaFile($filename, $content, $media_folder_id=false)
      • uploadMediaFile($filename, $uploaded_file, $media_folder_id=0)
    • Media Folders
      • getMediaFolders(){
      • getMediaFolder($id){
      • createMediaFolder($name){
  • Clases
    • Clase RestModel
      • delete()
      • update($attributes=[])
    • Clase CustomField
    • Clase Sender
      • sendConfirmationMail()
    • Clase Group
    • Clase Campaign
      • send()
    • Clase SentCampaign
      • clicks()
      • impressions()
      • sent_emails()
      • unsubscribe_events()
    • Clase CampaignFolder
    • Clase Import
      • data()
      • cancel()
    • Clase MediaFile
    • Clase MediaFolder

Instalación

composer require ajtarragona/mailrelay-client

Configuración

Puedes configurar el paquete a través del archivo .env de tu aplicación Laravel, a través de las siguientes variables de entorno:

MAILRELAY_API_URL
MAILRELAY_API_KEY
MAILRELAY_DEBUG

Alternativamente, puedes publicar en archivo de configuración a través del comando:

php artisan vendor:publish --tag=ajtarragona-mailrelay-config

Esto creará el archivo mailrelay.php en la carpeta config de tu aplicación Laravel.

Uso

Puedes usar el servicio de tres maneras diferentes:

A través de una Facade:

use MailRelay;
...
public  function  test(){
    $remitents=MailRelay::getSenders();
    ...
}

Nota: Para Laravel < 5.6, es necesario registrar el alias de la Facade en el archivo config/app.php de tu aplicación Laravel

'aliases'  =>  [
   ...
   'MailRelay'  =>  Ajtarragona\MailRelay\Facades\MailRelay::class
]

Vía Inyección de dependencias:

En tus controladores, helpers, modelo...

use Ajtarragona\MailRelay\MailRelayService;
...

public  function  test(MailRelayService  $mailrelay){
    $remitents=$mailrelay->getSenders();
    ...
}

Vía función helper:

...
public  function  test(){
    $remitents=mailrelay()->getSenders();
    ...
}

Funciones

Senders (Remitentes)

Un remitente es un objeto de la clase Sender

getSenders($page=null, $per_page=null)

Retorna todos los remitentes.

• $page: numero de pàgina (opcional)
• $per_page: registres per pàgina (opcional)

getSender($id)

Retorna un remitente

getDefaultSender()

Retorna el remitente por defecto

createSender($name, $email)

Añade un remitente

• $name: nombre del remitente
• $email: email del remitente

Custom Fields

Un custom field es un objeto de la clase CustomField

getCustomFields($page=null, $per_page=null)

Retorna todos los custom_fields de Mailrelay.

getCustomField($id)

Retorna un custom_fields

createCustomField($name, $label, $type="text", $required=false, $default_value="", $options=[])

Añade un custom field a mailrelay.

• $name: nombre corto interno
• $label: nombre visible
• $type : Tipo de campo. Soportados: text, textarea, number, select, select_multiple, checkbox, radio_buttons, date. (opcional, por defecto text)
• $required: Indica si será obligatorio (opcional, por defecto false)
• $default_value: Valor por defecto (opcional)

En caso de ser select, select_multiple, checkbox o radio_buttons:

• $options es un array con los nombres de las opciones

Groups

Un grupo es un objeto de la clase Group

getGroups($page=null, $per_page=null)

Retorna todos los grupos.

getGroup($id)

Retorna un grupo

createGroup($name, $description=null)

Añade un grupo

Campaigns (Boletines)

Un boletín es un objeto de la clase Campaign

getCampaigns($page=null, $per_page=null)

Retorna todos los boletines.

getCampaign($id)

Retorna un boletin

createCampaign($subject, $body, $sender_id, $group_ids=[], $target="groups", $attributes=[])

Añade un boletin

• $subject Asunto
• $body Cuerpo del boletín
• $sender_idId del remitente
• $group_idsArray de Ids de grupo (opcional)
• $target Indica si serà un boletín de grupos (groups) o de segmento (segment)
• $attributes Array con otros atributos opcionales que pasaremos a la API MailRelay.

Sent Campaigns (Informes de envio de Boletines)

Un informe de envio de boletín es un objeto de la clase SentCampaign

getSentCampaigns($page=null, $per_page=null)

Retorna todos los informes de envio de boletín.

getSentCampaign($id)

Retorna un informe de envio de boletín

Campaign Folders

Una carpeta es un objeto de la clase CampaignFolder

getCampaignFolders($page=null, $per_page=null)

Retorna todas las carpetas de boletín.

getCampaignFolder($id)

Retorna una carpeta de boletín

createCampaignFolder($name)

Añade una carpeta de boletín

• $name Nombre de la carpeta

Imports

Una importacion es un objeto de la clase Import

getImports($page=null, $per_page=null)

Retorna todas las importaciones.

getImport($id)

Retorna una importacion

createImport($filename, $subscribers, $group_ids=[], $callback=null, $ignore=true)

Añade una importacion

• $filename name of the file created in MailRelay
• $subscribers must be an array of subscribers. Each row must have the same key=>value fields. Custom fields key shold be: custom_field_ID
• $group_ids array of group IDs the users will be subscribed to
• $callback url
• $ignore by default existing users will be ignored

MailRelay::createImport("prueba api",[
  [
    "name"=>"juan",
    "email"=>"[e-mail]",
    "custom_field_17"=>"a"
  ],
  [
    "name"=>"Luis d'Àvila",
    "email"=>"[e-mail]",
    "custom_field_17"=>"bb"
  ]
],[13]);

Media Files

Un media file es un objeto de la clase MediaFile

getMediaFiles($page=null, $per_page=null)

Retorna todas las imagenes

getMediaFile($id){

Retorna una imagen

createMediaFile($filename, $content, $media_folder_id=false)

Añade una imagen

• $filename Nombre de la imagen
• $content Contenido biario de la imagen (no base64)

uploadMediaFile($filename, $uploaded_file, $media_folder_id=0)

Añade una imagen a partir de un upload

Media Folders

Un media folder es un objeto de la clase MediaFolder

getMediaFolders(){

Retorna las carpetas de media

getMediaFolder($id){

Retorna una carpeta de media

createMediaFolder($name){

Añade una carpeta de media.

Si ya existe con el mismo nombre, la devuelve

Clases

Clase RestModel

Los objetos que devuelve la API se devuelven como instancias de la clase RestModel. Sobre estos objetos podemos invocar los siguientes métodos:

delete()

Eliminará el objeto de MailRelay

$sender=MailRelay::getSender(2);
$sender->delete();

update($attributes=[])

Modificará los atributos pasados

$sender=MailRelay::getSender(2);
$sender->update([
    "name"=>"Nuevo nombre"
]);

Clase CustomField

Hereda de la clase RestModel

Clase Sender

Hereda de la clase RestModel

Métodos:

sendConfirmationMail()

Envía el mail de confirmación al remitente

$sender=MailRelay::getSender(2);
$sender->sendConfirmationMail();

Clase Group

Hereda de la clase RestModel

Clase Campaign

Hereda de la clase RestModel

Métodos:

send()

Envía el boletín. Retorna el informe de envio (un objeto SentCampaign)

$boletin=MailRelay::getCampaign(5);
$informe=$boletin->send();

Clase SentCampaign

Hereda de la clase RestModel

Métodos:

clicks()

Retona els clicks

impressions()

Retona les impressions

sent_emails()

Retona els emails enviats

unsubscribe_events()

Retona les desubscripcions

Clase CampaignFolder

Hereda de la clase RestModel

Clase Import

Hereda de la clase RestModel

Métodos:

data()

Devuelve los datos de la importación

cancel()

Cancela una importación si está en curso

Clase MediaFile

Hereda de la clase RestModel

Clase MediaFolder

Hereda de la clase RestModel