{"id":24190834,"url":"https://github.com/sprintcube/cakephp-sendgrid","last_synced_at":"2025-05-06T15:36:31.036Z","repository":{"id":41990407,"uuid":"150096068","full_name":"sprintcube/cakephp-sendgrid","owner":"sprintcube","description":"SendGrid plugin for CakePHP","archived":false,"fork":false,"pushed_at":"2025-01-10T11:36:00.000Z","size":71,"stargazers_count":5,"open_issues_count":4,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-10T12:31:37.939Z","etag":null,"topics":["cakephp","cakephp-plugin","cakephp3","cakephp4","email","php","sendgrid"],"latest_commit_sha":null,"homepage":"","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/sprintcube.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-24T12:02:05.000Z","updated_at":"2025-01-10T11:32:49.000Z","dependencies_parsed_at":"2024-10-28T07:30:18.893Z","dependency_job_id":"16753231-4814-44a1-9473-a72c6518ad7b","html_url":"https://github.com/sprintcube/cakephp-sendgrid","commit_stats":{"total_commits":38,"total_committers":3,"mean_commits":"12.666666666666666","dds":"0.10526315789473684","last_synced_commit":"0a7282742ac2d2d9eb944f8e69228a2b7a9d5b41"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintcube%2Fcakephp-sendgrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintcube%2Fcakephp-sendgrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintcube%2Fcakephp-sendgrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintcube%2Fcakephp-sendgrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sprintcube","download_url":"https://codeload.github.com/sprintcube/cakephp-sendgrid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233761318,"owners_count":18726115,"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","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":["cakephp","cakephp-plugin","cakephp3","cakephp4","email","php","sendgrid"],"created_at":"2025-01-13T15:01:47.548Z","updated_at":"2025-01-13T15:03:39.496Z","avatar_url":"https://github.com/sprintcube.png","language":"PHP","readme":"# SendGrid Plugin for CakePHP\n\n[![CI](https://github.com/sprintcube/cakephp-sendgrid/workflows/CI/badge.svg?branch=master)](https://github.com/sprintcube/cakephp-sendgrid/actions)\n[![codecov](https://codecov.io/gh/sprintcube/cakephp-sendgrid/branch/master/graph/badge.svg)](https://codecov.io/gh/sprintcube/cakephp-sendgrid)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)\n[![Latest Stable Version](https://poser.pugx.org/sprintcube/cakephp-sendgrid/v/stable)](https://packagist.org/packages/sprintcube/cakephp-sendgrid)\n[![Total Downloads](https://poser.pugx.org/sprintcube/cakephp-sendgrid/downloads)](https://packagist.org/packages/sprintcube/cakephp-sendgrid)\n\nThis plugin provides email delivery using [SendGrid](https://sendgrid.com/).\n\nThis branch is for use with **CakePHP 5.0+**. For other versions of CakePHP, please use the following version map.\n\n\n| SendGrid Plugin | Branch | CakePHP Core|\n| --- | --- | --- |\n| 1.x **[EOL]** | [cake-3.x](https://github.com/sprintcube/cakephp-sendgrid/tree/cake-3.x) | 3.4+ |\n| 4.x | [cake-4.x](https://github.com/sprintcube/cakephp-sendgrid/tree/cake-4.x) | 4.0+ |\n| 5.x (in progress) | [master](https://github.com/sprintcube/cakephp-sendgrid/tree/master) | 5.0+ |\n\n## Requirements\n\nThis plugin has the following requirements:\n\n* CakePHP 5.0 or greater.\n* PHP 8.1 or greater.\n\n## Installation\n\nYou can install this plugin into your CakePHP application using [composer](http://getcomposer.org).\n\n```\ncomposer require sprintcube/cakephp-sendgrid\n```\n\nAfter installation, [Load the plugin](http://book.cakephp.org/3.0/en/plugins.html#loading-a-plugin)\n```php\nPlugin::load('SendGrid');\n```\nOr, you can load the plugin using the shell command\n```sh\n$ bin/cake plugin load SendGrid\n```\n\n## Setup\n\nSet your SendGrid Api key in `EmailTransport` settings in app.php\n\n```php\n'EmailTransport' =\u003e [\n...\n  'sendgrid' =\u003e [\n      'className' =\u003e 'SendGrid.SendGrid',\n      'apiKey' =\u003e 'your-api-key' // your api key\n  ]\n]\n```\nAnd create new delivery profile in `Email` settings.\n\n```php\n'Email' =\u003e [\n    'default' =\u003e [\n        'transport' =\u003e 'default',\n        'from' =\u003e 'you@localhost',\n        //'charset' =\u003e 'utf-8',\n        //'headerCharset' =\u003e 'utf-8',\n    ],\n    'sendgrid' =\u003e [\n        'transport' =\u003e 'sendgrid'\n    ]\n]\n```\n\n## Usage\n\nYou can now simply use the CakePHP `Email` to send an email via SendGrid.\n\n```php\n$email = new SendGridMailer();\n$email-\u003esetFrom(['you@yourdomain.com' =\u003e 'CakePHP SendGrid'])\n    -\u003esetTo('foo@example.com.com')\n    -\u003eaddTo('bar@example.com')\n    -\u003eaddCc('john@example.com')\n    -\u003esetSubject('Email from CakePHP SendGrid plugin')\n    -\u003edeliver('Message from CakePHP SendGrid plugin');\n```\n\nThat is it.\n\n## Advance Use\nYou can also use few more options to send email via SendGrid APIs. To do so, just call the appropriate methods before sending the email.\n\n### Custom Headers\nYou can pass your own headers. It must be prefixed with \"X-\". Use the default `Email::setHeaders` method like,\n\n```php\n$email = new SendGridMailer();\n$email-\u003esetFrom(['you@yourdomain.com' =\u003e 'CakePHP SendGrid'])\n    -\u003esetTo('foo@example.com.com')\n    -\u003esetHeaders([\n        'X-Custom' =\u003e 'headervalue',\n        'X-MyHeader' =\u003e 'myvalue'\n    ])\n    -\u003esetSubject('Email from CakePHP SendGrid plugin')\n    -\u003edeliver('Message from CakePHP SendGrid plugin');\n```\n\n\u003e When sending request, `X-` will be removed from header name e.g. X-MyHeader will become MyHeader\n\n### Attachments\nSet your attachments using `Email::setAttachments` method.\n\n```php\n$email = new SendGridMailer();\n$email-\u003esetFrom(['you@yourdomain.com' =\u003e 'CakePHP SendGrid'])\n    -\u003esetTo('foo@example.com.com')\n    -\u003esetSubject('Email from CakePHP SendGrid plugin')\n    -\u003esetAttachments([\n        'cake_icon1.png' =\u003e Configure::read('App.imageBaseUrl') . 'cake.icon.png',\n        'cake_icon2.png' =\u003e ['file' =\u003e Configure::read('App.imageBaseUrl') . 'cake.icon.png'],\n        WWW_ROOT . 'favicon.ico'\n    ])\n    -\u003edeliver('Message from CakePHP SendGrid plugin');\n```\n\n\u003e To send inline attachment, use `contentId` parameter while setting attachment.\n\n### Template\nYou can use the template created in SendGrid backend. Get the template id by either using their API or from the URL.\nSet the template id using `setTemplate` method.\n\n```php\n$email = new SendGridMailer();\n$email-\u003esetTo('foo@example.com.com')\n    -\u003esetTemplate('d-xxxxxx')\n    -\u003edeliver();\n```\n\n### Schedule\nYou can schedule the email to be sent in future date. You can set upto 72 hours in future as per SendGrid documentation. You need to pass a unix timestamp value.\n\n```php\n$email = new SendGridMailer();\n$email-\u003esetTo('foo@example.com.com')\n    -\u003esetSendAt(1649500630)\n    -\u003edeliver();\n```\n## Webhooks\nYou can receive status events from SendGrid. This allows you ensure that SendGrid was able to send the email recording bounces etc. \n\n### Webhook Config\nYou will require a Table in the database to record the emails sent. You can use the lorenzo/cakephp-email-queue plugin to queue the emails and in that case you would \nuse the email_queue table. However you can create your own table/Model as long as it has at least three columns. They can be called anything but they must have the correct types.\n\nWhen you send the email the deliver function will return an array with a 'messageId' element if it successfully connected to SendGrid. This needs to be recorded in the status_id field.\n\n* status_id VARCHAR(100)\n* status VARCHAR(100)\n* status_message TEXT\n\nYou need to map this table and these fields in you app_local.php config\n\n```php\n\n    'sendgridWebhook' =\u003e [\n        'tableClass' =\u003e 'EmailQueue', // The table name that stores email data\n        'uniqueIdField' =\u003e 'status_id', // The field name that stores the unique message ID VARCHAR(100)\n        'statusField' =\u003e 'status', // The field name that stores the status of the email status VARCHAR(100)\n        'statusMessageField' =\u003e 'status_message', // The field name that stores the status messages TEXT\n        'debug' =\u003e 'true', // write incoming requests to debug log\n        'secure' =\u003e 'true', // enable SendGrid signed webhook security. You should enable this in production\n        'verification_key' =\u003e '\u003cYOUR VERIFICATION KEY\u003e', // The verification key from SendGrid\n    ],\n\n```\n\nYou will need to login to your SendGrid Account and configure your domain and the events that you want to track\n\n https://app.sendgrid.com/settings/mail_settings/webhook_settings\n\nThe return url needs to be set to \n* https://YOURDOMAIN/send-grid/webhook\n\n\nThe CSRF protection middleware needs to allow posts to the webhooks controller in Application.php\nRemove the current CSRF protection middleware and replace it with the following. If you already have CSRF exceptions then add the Webhooks one\n  \n  ```php\n    $csrf = new CsrfProtectionMiddleware();\n\n    $csrf-\u003eskipCheckCallback(function ($request) {\n           // Skip token check for API URLs.\n          if ($request-\u003egetParam('controller') === 'Webhooks') {\n             return true;\n            }\n    });\n \n      // Ensure routing middleware is added to the queue before CSRF protection middleware.\n    $middlewareQueue-\u003eadd($csrf);\n \n    return $middlewareQueue;\n  \n  ```\n\nIf the authentication plugin (https://book.cakephp.org/authentication/3/en/index.html) is used for authentication the webhook action should work OK. If you have a different authentication method then you will need to add an exception for the webhook action. /send-grid/webhooks/index \n\n#### Webhook Signature Verification\nSendGrid allows you to sign the webhook requests. This is a good idea in production to keep the webhook secure. You will need to enable this in your SendGrid account and then set secure to true and add your verification key to your app_local.php config file.\n\nhttps://docs.sendgrid.com/for-developers/tracking-events/getting-started-event-webhook-security-features. Enable signed event webhook and follow the instructions to get the verification key.\n\n## Reporting Issues\n\nIf you have a problem with this plugin or any bug, please open an issue on [GitHub](https://github.com/sprintcube/cakephp-sendgrid/issues).\n","funding_links":[],"categories":["Email"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsprintcube%2Fcakephp-sendgrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsprintcube%2Fcakephp-sendgrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsprintcube%2Fcakephp-sendgrid/lists"}