This class helps you to use the mailing functionality of MailUp platform with your Laravel 5.x framework.
Using composer insert into composer.json the following code block:
"repositories": [
{
"url": "https://github.com/caereservices/mailup.git",
"type": "git"
}
], ...
"require": {
"caereservices/mailup": "dev-master", ...
then run composer update
Following example show the basic steps for use this class in your code.
use Caereservices\Mailup\MailupStatus;
use Caereservices\Mailup\MailupException;
use Caereservices\Mailup\MailupClient;
$CLIENT_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
$CLIENT_SECRET = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
$CALLBACK_URI = "http://localhost/callback_uri";
$USER = "mXXXXXX";
$PASSWORD = "xxxxxxxxx";
$mailUp = null;
try {
$mailUp = new MailupClient($CLIENT_ID, $CLIENT_SECRET, $CALLBACK_URI);
if( $mailUp ) {
$result = $mailUp->login($USER, $PASSWORD);
if( $result == MailupStatus::OK ) {
...
}
}
} catch (MailupException $e) {
...
}
$CLIENT_ID and $CLIENT_SECRET can be obtained follow these guide
$result = $mailUp->login(<USER>, <PASSWORD> [, <LISTNAME>]);
Parameters:
- USER : Username for Mailup platform (usually mXXXXX)
- PASSWORD : Password for Mailup platform
- LISTNAME : (optional) The name of list of recipients to use, if not specified default list of Mailup is used
Return values:
- MailupStatus::OK - logged in correctly
- MailupStatus::ERR_NOT_LOGGED_IN - Username or password are incorrectly
- MailupStatus::ERR_INVALID_PARAMETER - One or many parameter ar invalid or empty
- MailupStatus::ERR_MAILUP_EXCEPTION - Mailup Platform exception
- MailupStatus::ERR_LIST_NOT_FOUND - If LISTNAME is specified but not exist in Mailup platform
$result = $mailUp->createList(<LISTNAME>, <LISTDATA>);
Parameter:
- LISTNAME : The name of list of recipients to use
- LISTDATA : Array with fields for fill List data
LISTDATA Fields
- name - Name of the List
- main_mail - Main email address linked to the list
- reply_to - Mail address for reply from user
- sender_name - Sender name that appear to user when receive mail
- company_name - Your company name
- contact_name - Contact name in company (unnecessary match main_mail or reply_to owner)
- address - Your company address
- city - Your company city
- country_code - Your country code (ex. IT)
- perm_remind - Permission reminder (default "") see here for information
- web_site - Your website URL
All fields are mandatory
Return values:
- MailupStatus::OK - List created correctly
- MailupStatus::ERR_NOT_LOGGED_IN - The method are called without make login
- MailupStatus::ERR_INVALID_PARAMETER - One or many parameter ar invalid or empty
- MailupStatus::ERR_MAILUP_EXCEPTION - Mailup Platform exception
- MailupStatus::ERR_LIST_NOT_CREATED - The LISTNAME not exist in Mailup platform and cannot be created
- MailupStatus::ERR_NO_LIST_DATA - The LISTDATA array is empty or null
- MailupStatus::ERR_INVALID_LIST_DATA - The LISTDATA array have one or many fields empty or null
$result = $mailUp->changeList(<LISTNAME> [, <LISTDATA>]);
If LISTNAME doesn't exist the and LISTDATA array is specified method try to create it
Parameter:
- LISTNAME : The name of list of recipients to use
- LISTDATA : (optional) Array with fields for fill List data (see createList for array structure)
Return values:
- MailupStatus::OK - List changed correctly
- MailupStatus::ERR_NOT_LOGGED_IN - The method are called without make login
- MailupStatus::ERR_INVALID_PARAMETER - One or many parameter ar invalid or empty
- MailupStatus::ERR_MAILUP_EXCEPTION - Mailup Platform exception
- MailupStatus::ERR_LIST_NOT_CREATED - The LISTNAME not exist in Mailup platform and cannot be created
- MailupStatus::ERR_LIST_NOT_CHANGED - The LISTNAME is invalid and the current list remain unchanged
$result = $mailUp->addGroup(<GROUPNAME>);
Parameter:
- GROUPNAME : The name of the group to be created
Return values:
- (number > 0) - Group created and it's ID are returned, if the Group exist the method return it's ID.
- MailupStatus::ERR_NOT_LOGGED_IN - The method are called without make login
- MailupStatus::ERR_INVALID_PARAMETER - One or many parameter are invalid or empty
- MailupStatus::ERR_MAILUP_EXCEPTION - Mailup Platform exception
- MailupStatus::ERR_CREATING_GROUPS - The GROUPNAME not exist in Mailup platform and cannot be created
$result = $mailUp->addUserToGroup(<USERDATA>, <GROUPNAME>);
Parameters:
- USERDATA : Array with User data to be added to group
- GROUPNAME : The name of the group (can be a Group ID also)
USERDATA Fields
- mail - User email (mandatory)
- name - User firstname
- surname - User lastname
- mobile - User mobile number without international prefix (ex. +39xxxxxxx)
- company - User company name (if available)
Return values:
- MailupStatus::OK - User created created or User exist in platform
- MailupStatus::ERR_NOT_LOGGED_IN - The method are called without make login
- MailupStatus::ERR_INVALID_PARAMETER - One or many parameter are invalid or empty
- MailupStatus::ERR_MAILUP_EXCEPTION - Mailup Platform exception
- MailupStatus::ERR_GETTING_FIELDS This error is returned when we have a problem with dynamic fields of Mailup (see here for details)
- MailupStatus::ERR_INVALID_USERDATA - The USERDATA contains invalid data or incorrect field
- MailupStatus::ERR_ADDING_USER - The user cannot be created (added)
$result = $mailUp->sendMessage(<SUBJECT>, <MESSAGE>, <GROUPNAME>, <USERMAILS>, <ATTACHMENT>);
Parameters:
- SUBJECT - Subject of message
- MESSAGE - Text of message (can be plain text or HTML)
- GROUPNAME - The name of the group to send a message
- USERMAILS - The mail of the user(s) to send a message, can be a single mail address or array of mail address
- ATTACHMENT - Path to the file/image/other to attach at the message (MUST be, if present, absolute path to file, if it stay on the server, or URL), if the class don't found the attachment no data is attached to message
If either of GROUPNAME and/or USERMAILS aren't specified ("" or null is passed) the message is sent to ALL recipients (users) present in the current List.
Return values:
- MailupStatus::MESSAGE_SENDED - The message is correctly queued and be sended as soon as possible
- MailupStatus::ERR_NOT_LOGGED_IN - The method are called without make login
- MailupStatus::ERR_INVALID_PARAMETER - One or many parameter ar invalid or empty
- MailupStatus::ERR_MAILUP_EXCEPTION - Mailup Platform exception
- MailupStatus::ERR_MESSAGE_NOT_SENDED - The message cannot be sended
- MailupStatus::ERR_CANT_CREATE_MESSAGE - The system cannot create (prepare) the message before send it
- MailupStatus::ERR_MESSAGE_TEXT_EMPTY - The MESSAGE parameter is empty or null
$result = $mailUp->getTemplateList();
Almost one Mail Template MUST be created belong Mailup platform before using this method and methods linked, you can find all information and guide on templates here
Return values:
- TemplateListStructure - Template list present on Mailup platform
- MailupStatus::ERR_NO_TEMPLATES - There isn't template in Mailup platform
- MailupStatus::ERR_NOT_LOGGED_IN - The method are called without make login
- MailupStatus::ERR_MAILUP_EXCEPTION - Mailup Platform exception
- MailupStatus::ERR_UNKNOW_LIST - The current List have a problem
$result = $mailUp->sendFromTemplate(<TEMPLATEID>, <GROUPNAME>, <USERMAILS>, <ATTACHMENT>);
SUBJECT and MESSAGE are obviously unnecessary :)
Refer to sendMessage for most parameter and return values except follows
Parameter:
- TEMPLATEID - Template's ID obtained from selected item of getTemplateList returned list
Return values:
- MailupStatus::ERR_NO_TEMPLATES - The template ID is incorrect or invalid
For all reference and specification on API call for Mailup platform refer here
Based on example code from here
Massimo Villalta - (c) 2017 - Caereservices.it