{"id":22413053,"url":"https://github.com/bertoost/craft-cms-mandrill-service","last_synced_at":"2025-07-23T15:05:47.447Z","repository":{"id":62493431,"uuid":"118981276","full_name":"bertoost/Craft-CMS-Mandrill-Service","owner":"bertoost","description":"Mandrill service plugin for Craft CMS v2 - Please install via Composer","archived":false,"fork":false,"pushed_at":"2018-11-28T08:22:28.000Z","size":187,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-06-03T01:25:38.908Z","etag":null,"topics":["craftcms","craftcms-plugin","mandrill"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/bertoost/craft-mandrill-service-plugin","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bertoost.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-25T23:49:09.000Z","updated_at":"2018-11-28T08:22:29.000Z","dependencies_parsed_at":"2022-11-02T09:31:59.784Z","dependency_job_id":null,"html_url":"https://github.com/bertoost/Craft-CMS-Mandrill-Service","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/bertoost/Craft-CMS-Mandrill-Service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoost%2FCraft-CMS-Mandrill-Service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoost%2FCraft-CMS-Mandrill-Service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoost%2FCraft-CMS-Mandrill-Service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoost%2FCraft-CMS-Mandrill-Service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bertoost","download_url":"https://codeload.github.com/bertoost/Craft-CMS-Mandrill-Service/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bertoost%2FCraft-CMS-Mandrill-Service/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266699570,"owners_count":23970517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["craftcms","craftcms-plugin","mandrill"],"created_at":"2024-12-05T14:11:44.467Z","updated_at":"2025-07-23T15:05:47.418Z","avatar_url":"https://github.com/bertoost.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mandrill service plugin for Craft CMS (v2)\n\nThis plugin provides the ability to send emails via Mandrill API. It also can control all of the emails send by Craft's EmailService being captured for sending to Mandrill. Read below for more information.\n\n\u003c!-- TOC depthFrom:2 --\u003e\n\n- [Installation](#installation)\n    - [Composer vendor files](#composer-vendor-files)\n    - [Enable the plugin in Craft](#enable-the-plugin-in-craft)\n    - [Configuration settings](#configuration-settings)\n        - [API Key](#api-key)\n        - [Enable as a service](#enable-as-a-service)\n        - [From settings](#from-settings)\n        - [Craft's general config to override](#crafts-general-config-to-override)\n- [Take over control of all outgoing emails](#take-over-control-of-all-outgoing-emails)\n    - [Manually use the service](#manually-use-the-service)\n- [Events](#events)\n    - [email.onBeforeSendEmail](#emailonbeforesendemail)\n    - [email.onSendEmail](#emailonsendemail)\n    - [email.onSendEmailError](#emailonsendemailerror)\n- [Examples](#examples)\n    - [Add-in tags](#add-in-tags)\n    - [Using attachments](#using-attachments)\n    - [Set a schedule date/time](#set-a-schedule-datetime)\n- [Outbound view](#outbound-view)\n\n\u003c!-- /TOC --\u003e\n\n## Installation\n\nFrom the root of your Craft installation, just run composer to install this plugin;\n\n```terminal\ncomposer require bertoost/craft-mandrill-service-plugin\n```\n\nThis will install the plugin inside your `craft/plugins/` folder automatically.\n\n### Composer vendor files\n\nIt also brings some other vendor files inside the `vendor/` directory in your project root. This can be ignored by your VCS or included when you aren't able to run `composer install` at your hosting-server.\n\nMaybe your installation is configured to use another path structure. If the plugin can't find the Composer `vendor/` folder, it will notify you in the admin panel. To solve it, you can tell us where to find the `vendor/` folder. Just add this line to your websites' index.php file, just below the `$craftPath` definition.\n\n```php\ndefine('COMPOSER_VENDOR_PATH', realpath('../vendor/'));\n```\n\n### Enable the plugin in Craft\n\nNavigate to Craft's settings \u003e Plugins \u003e Install `Mandrill Service` plugin.\n\n### Configuration settings\n\n![Settings](resources/docs/screenshots/settings-page.png \"Settings\")\n\n#### API Key\n\nAfter installation you have to configure the plugin to work at all. Navigate to the plugin settings page and enter the API key you want to use.\n\n__Remember:__ Mandrill provides the ability to have a test-API-key. You can test it as many times you want without having a paid account already. Login to Mandrill and activate a \"Test\" API key.\n\n#### Enable as a service\n\nThere are two ways of using this plugin. You can use the Mandrill service or let it take over control of sending any email, sent by Craft's EmailService. This is a setting in the plugin;\n\n#### From settings\n\nThe from email and name settings are meant to configure the sender name for your site/application. This can be overwritten when using manual service, but this config settings are used by default.\n\n#### Craft's general config to override\n\nYou can pass the following settings to the `general.php` configuration file of Craft, to override the settings in the settings page from the plugin.\n\n```php\nreturn [\n    // ...\n    'mandrillEnabled'   =\u003e false,\n    'mandrillApiKey'    =\u003e 'TheKeyFromMandrill',\n    'mandrillFromEmail' =\u003e 'you@address.mail',\n    'mandrillFromName'  =\u003e 'Your Sender Name',\n];\n```\n\n## Take over control of all outgoing emails\n\n__Downside (read carefully):__\n\nThe plugin hooks on the `email.onBeforeSendEmail` event and disables any further process of Craft's EmailService (by setting `$event-\u003eperformAction = false;`). It also will re-fire that event, to be sure all data from any plugin is captured before sending it.\n\nSo, why is this a bad thing?\nBecause it can happen (actually: it will!) that your plugin already did it's work before this event reaches the Mandrill-take-over part. But when not, we fire the event again to be sure it will. This will cause a second roundtrip of the `email.onBeforeSendEmail` event.\nDepending on what happens on this event, it can slow down the process!\n\nIf you're building heavy stuff on this event, it can be good to check if you did your thing already. Like this;\n\n```php\ncraft()-\u003eon('email.onBeforeSendEmail', function (Event $event) {\n\n    // check if we've been here before\n    if (!isset($event-\u003eparams['myplugin_beenHere'])) {\n\n        // do your stuff here\n\n        $event-\u003eparams['myplugin_beenHere'] = true;\n    }\n});\n```\n\nIt will not stop coming here twice, but the hard part (or load/performance taking part) of your code will be skipped.\n\n### Manually use the service\n\nIt's also possible to use the Mandrill service manually.\n\n```php\n$variables = [\n    // any template variables\n];\n\n$htmlBody = /* Some HTML content, parsed by Twig?! */;\n$plainTextBody = /* Some plain text content, parsed by Twig?! */;\n\ncraft()-\u003emandrill\n    -\u003eaddTo('email@ddre.ss', 'Sender Name')\n    -\u003esetContent($htmlBody, $plainTextBody, $variables)\n    -\u003esend();\n```\n\nUsing Craft's messages system\n\n```php\n// get any UserModel anyhow, example:\n$user = craft()-\u003eusers-\u003egetUserByEmail('me@example.com');\n\n$variables = [\n    // any template variables\n];\n\ncraft()-\u003emandrill\n    -\u003esetUser($user)\n    -\u003esetByEmailKey('the_message_key', $variables)\n    -\u003esend();\n```\n\n## Events\n\nThe Craft email events are still being used. They contain the same params as the event is getting from Craft's default EmailService.\n\n```php\n[\n    'user'       =\u003e /* an UserModel */,\n    'emailModel' =\u003e /* an EmailModel */,\n    'variables'  =\u003e /* an array of variables */,\n\n    // and on error:\n    'error'      =\u003e /* error message */,\n]\n```\n\nAdditional params are added by the Mandrill service\n\n### email.onBeforeSendEmail\n\n```php\n[\n    // ...\n    '_mandrill'    =\u003e true,\n    'emailMessage' =\u003e /* a Mandrill_MessageModel */,\n]\n```\n\n### email.onSendEmail\n\n```php\n[\n    // ...\n    '_mandrill'    =\u003e true,\n    'emailMessage' =\u003e /* a Mandrill_MessageModel */,\n    'result'       =\u003e /* array of the Mandrill API result */,\n]\n```\n\n### email.onSendEmailError\n\n```php\n[\n    // ...\n    '_mandrill'    =\u003e true,\n    'emailMessage' =\u003e /* a Mandrill_MessageModel */,\n]\n```\n\n## Examples\n\nFind some example usages below\n\n### Add-in tags\n\nYour plugin can add tags to email messages easily since the `emailMessage` is passed by the events given by the Mandrill plugin. Example;\n\n__When using service manually;__\n\n```php\n// attachment as content\ncraft()-\u003emandrill\n    // ...\n    -\u003eaddAttachment('my.pdf', $fileContents, 'application/pdf');\n\n// or as a file path\ncraft()-\u003emandrill\n    // ...\n    -\u003eaddAttachmentFile('path/to/my.pdf', 'alternate-name.pdf', 'application/pdf')\n```\n\n__When the \"Mandrill as service\" is on;__\n\n```php\ncraft()-\u003eon('email.onBeforeSendEmail', function (Event $event) {\n\n    // to be sure it happens when Mandrill is here\n    if (isset($event-\u003eparams['_mandrill'])) {\n\n        // single one\n        $event-\u003eparams['emailMessage']\n            -\u003eaddTag('Tag name one')\n            -\u003eaddTag('Tag name two');\n\n        // or as array\n        $event-\u003eparams['emailMessage']\n            -\u003eaddTag(['Tag name one', 'Tag name two']);\n\n        // based on messages-system email-key\n        switch ($event-\u003eparams['variables']['emailKey']) {\n            case 'forgot_password':\n                $event-\u003eparams['emailMessage']\n                    -\u003eaddTag('Forgot password');\n                break;\n        }\n    }\n});\n```\n\n### Using attachments\n\n__When using service manually;__\n\n```php\n// attachment as content\ncraft()-\u003emandrill\n    // ...\n    -\u003eaddAttachment('my.pdf', $fileContents, 'application/pdf');\n\n// or as a file path\ncraft()-\u003emandrill\n    // ...\n    -\u003eaddAttachmentFile('path/to/my.pdf', 'alternate-name.pdf', 'application/pdf')\n```\n\n__When the \"Mandrill as service\" is on;__\n\n```php\ncraft()-\u003eon('email.onBeforeSendEmail', function (Event $event) {\n\n    // to be sure it happens when Mandrill is here\n    if (isset($event-\u003eparams['_mandrill'])) {\n\n        $event-\u003eparams['emailMessage']\n            -\u003eaddAttachment('my.pdf', $fileContents, 'application/pdf');\n    }\n});\n```\n\n### Set a schedule date/time\n\n__When using service manually;__\n\n```php\n$dateTime = new DateTime();\n$dateTime-\u003emodify('+2 hours');\n\ncraft()-\u003emandrill\n    // ...\n    -\u003esetSentAt($dateTime);\n```\n\n__When the \"Mandrill as service\" is on;__\n\n```php\ncraft()-\u003eon('email.onBeforeSendEmail', function (Event $event) {\n\n    // to be sure it happens when Mandrill is here\n    if (isset($event-\u003eparams['_mandrill'])) {\n\n        $dateTime = new DateTime();\n        $dateTime-\u003emodify('+2 hours');\n\n        $event-\u003eparams['mandrillSentAt'] = $dateTime;\n    }\n});\n```\n\n## Outbound view\n\nThe plugin comes with a very cool overview where you can see the outbound of Mandrill. It shows you if messages are sent correctly and also gives you an inside when it failes or bounces. All of this can be found in Mandrill too of course.\n\n![Outbound page](resources/docs/screenshots/outbound-page-example.png \"Outbound page\")\n\nTo enable this feature, you have to add a sync script to your cronjob system. This is the call you have to make (for example 1 to 4 times a day).\n\n```terminal\nphp craft/app/etc/console/yiic mandrill syncOutbound\n```\n\nYou can also use this command to sync it manually.\n\n__Note:__ This command scans Mandrill till 4 days in the past. Since bounces are being tried a couple of times.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbertoost%2Fcraft-cms-mandrill-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbertoost%2Fcraft-cms-mandrill-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbertoost%2Fcraft-cms-mandrill-service/lists"}