PHPackages                             nyco/wp-send-me-nyc - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. nyco/wp-send-me-nyc

ActiveWordpress-muplugin[Mail & Notifications](/categories/mail)

nyco/wp-send-me-nyc
===================

A developer plugin for WordPress that enables sharing website links via SMS or Email.

1.6.6(4y ago)1160[2 PRs](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/pulls)GPL-3.0+PHP

Since Nov 18Pushed 3y ago14 watchersCompare

[ Source](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc)[ Packagist](https://packagist.org/packages/nyco/wp-send-me-nyc)[ Docs](https://github.com/cityofnewyork/nyco-wp-send-me-nyc)[ RSS](/packages/nyco-wp-send-me-nyc/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (25)Used By (0)

NYCO Send Me NYC for WordPress
==============================

[](#nyco-send-me-nyc-for-wordpress)

A developer plugin for WordPress that enables sharing website links via SMS or Email. It uses [Twilio](https://www.twilio.com/) for the SMS service, [Amazon SES](https://aws.amazon.com/ses/) for the email service, the official [WordPress Bit.ly Plugin](https://wordpress.org/plugins/wp-bitly/) for url shortening, [Timber](https://www.upstatement.com/timber/) for email template rendering, and [WordPress Multilingual Plugin](https://wpml.org/) for translating email content.

Installation using [Composer](https://getcomposer.org/)
-------------------------------------------------------

[](#installation-using-composer)

**$1** This package uses [Composer Installers](https://github.com/composer/installers) to install the package in the **Must Use** plugins directory (*/wp-content/mu-plugins*):

```
composer require nyco/wp-send-me-nyc
```

*Not using Composer?* Download an archive of the code and drop it into the mu-plugins directory. However,other dependencies will need to be downloaded and installed separately.

**$2** [Create a proxy PHP loader file](https://wordpress.org/support/article/must-use-plugins/#caveats) inside the mu-plugins directory, or [use the one included with the plugin](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/blob/master/autoloader-sample.php):

```
mv wp-content/mu-plugins/wp-send-me-nyc/autoloader-sample.php wp-content/mu-plugins/send-me-nyc.php
```

Initialization
--------------

[](#initialization)

The [sample autoloader](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/blob/master/autoloader-sample.php) contains the basic code required to initialize the plugin. It will...

- Require all files containing classes and helper functions.
- Initialize the [`SMNYC\ContactMe`](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/blob/master/ContactMe.php), [`SMNYC\SmsMe`](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/blob/master/SMSMe.php), and [`SMNYC\EmailMe`](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/blob/master/EmailMe.php) classes.
- Register admin actions for [sending a message](#sending-a-message).
- Register [custom post types](#custom-post-types) for custom SMS and Email content (SMNYC Emails and SMNYC SMS).
- Create an admin settings page under *Settings > Send Me NYC* for [configuration](#configuration).

**Note:** The `SMNYC\SmsMe` and `SMNYC\EmailMe` classes extend the `SMNYC\ContactMe` class. Any of the three could be extended further or have their properties modified to accommodate custom settings or services.

Configuration
-------------

[](#configuration)

Each settings section corresponds to a specific service that needs to be configured to work with your WordPress installation. These can be configured in the WordPress admin settings or as PHP constants. If both the WordPress admin setting and the PHP constant setting of the option are set, the WordPress admin setting will be preferred.

### Bitly Service Settings for URL Shortening

[](#bitly-service-settings-for-url-shortening)

Admin SettingPHP ConstantSettings > Writing > Bitly OAuth Token`SMNYC_WPBITLY_OAUTH_TOKEN`The official [WordPress Bit.ly Plugin](https://wordpress.org/plugins/wp-bitly/) is used to manage the API version and authentication to Bit.ly. Once installed, Bit.ly settings can be found under Settings > Writing in the WordPress Admin Menu. Authentication requires access to a Bit.ly account or an Access Token. An Access Token can be generated by a Bit.ly user account in the developer settings. To use Oauth, a token will need to be generated programmatically or via the command line. Review the [API authentication documentation](https://dev.bitly.com/docs/getting-started/authentication) for more information.

The PHP Constant `SMNYC_WPBITLY_OAUTH_TOKEN` can be used to define the token. This plugin will set the WordPress Bit.ly token automatically and hide the authentication button.

### Twilio Service Settings for SMS

[](#twilio-service-settings-for-sms)

Admin SettingWordPress OptionPHP ConstantAccount SID`smnyc_twilio_user``SMNYC_TWILIO_USER`Sender Phone Number`smnyc_twilio_from``SMNYC_TWILIO_FROM`API Key SID`smnyc_twilio_api_key_sid``SMNYC_TWILIO_API_KEY_SID`API Key Secret`smnyc_twilio_api_key_secret``SMNYC_TWILIO_API_KEY_SECRET`The Twilio integration uses API Keys that can be generated under the Account > API Keys & Tokens page. Read more [about Twilio API keys here](https://www.twilio.com/docs/iam/keys/api-key-resource).

### Amazon SES Settings for Email

[](#amazon-ses-settings-for-email)

Admin SettingWordPress OptionPHP ConstantKey`smnyc_aws_user``SMNYC_AWS_USER`Secret`smnyc_aws_secret``SMNYC_AWS_SECRET`From Email Address`smnyc_aws_from``SMNYC_AWS_FROM`Email Display Name (optional)`smnyc_aws_display_name``SMNYC_AWS_DISPLAY_NAME`Reply-to (optional)`smnyc_aws_reply``SMNYC_AWS_REPLY`**Note:** This plugin works nicely with the [NYCO WordPress Config](https://github.com/CityOfNewYork/nyco-wp-config) plugin.

Custom Post Types
-----------------

[](#custom-post-types)

These custom post types are created to store reusable SMS and Email content that is sent in our messages.

### SMNYC SMS

[](#smnyc-sms)

An example of post content could include the following;

> REMINDER: you may be eligible for these NYC Programs: {{ BITLY\_URL }}

The template tag `{{ BITLY_URL }}` will be replaced with a shortened Bitly url that is intended to be shared with the recipient. The SMNYC SMS post type does not require any specific templating.

For more dynamic content, you can include an input for `sharetext` and include the template tag `{{ SHARE_TEXT }}` into the post content.

> {{ SHARE\_TEXT }} {{ BITLY\_URL }}

### SMNYC Email

[](#smnyc-email)

An example of post content could be the same as the SMS, however, you may not need to use the Bitly shortener for the url. In this case, replace `{{ BITLY_URL }}` with `{{ URL }}`.

> REMINDER: you may be eligible for these NYC Programs: {{ URL }}

The SMNYC Email post type requires a template controller that extends the [`Timber\Post` class](https://timber.github.io/docs/reference/timber-post/) and a [Twig](https://twig.symfony.com/) file containing the template that will render the content into an HTML email. The [sample controller](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/blob/master/controllers/smnyc-email-sample.php) contains a working class that extends `Timber\Post`. Move this file to the root of your active theme directory.

```
mv wp-content/mu-plugins/nyco-wp-send-me-nyc/controllers/smnyc-email-single-sample.php wp-content/themes/theme/smnyc-email.php
```

The [sample email](https://github.com/CityOfNewYork/nyco-wp-send-me-nyc/blob/master/views/email/single-sample.twig) contains a working email twig template. Use this file or create a file within your [Timber Views](https://timber.github.io/docs/guides/template-locations/#changing-the-default-folder-for-twig-files) directory called *emails/single.twig*. This is where the HTML markup for your email will be placed.

**Customization**

The path to the controller file and class contents can be used as is or modified as needed. By default, `SMNYC\EmailMe` requires a file called `smnyc-email.php` in the root of the activated WordPress theme that contains the the controller class. However, different path can be passed to the `SMNYC\EmailMe` class on instantiation in the [auto loader](#initialization);

```
$email = new SMNYC\EmailMe('controllers/smnyc-email.php');
```

Examining the `smnyc-email.php` file, we can see that the class has a template constant.

```
/** The twig template for emails */
const TEMPLATE = 'emails/single.twig';
```

This is the path inside the [*views*](https://timber.github.io/docs/guides/template-locations/#changing-the-default-folder-for-twig-files) where the email template is stored. Modify the string with a different path if desired. The `smnyc-email.php` also contains a method called `->addToPost()` where programmable post content can be added to pass to the view when it is rendered.

Sending a Message
-----------------

[](#sending-a-message)

WordPress Admin Ajax is used to send data from the front-end to the plugin. The `createEndpoints()` method of the instantiated `SMNYC\EmailMe` and `SMNYC\SmsMe` objects will add ajax actions when the plugin is initialized. Actions using [`wp_ajax_{$_REQUEST[‘action’]}`](https://developer.wordpress.org/reference/hooks/wp_ajax__requestaction/) and [`wp_ajax_nopriv_{$_REQUEST[‘action’]}`](https://developer.wordpress.org/reference/hooks/wp_ajax_nopriv__requestaction/) are registerd. Hidden inputs can be used to configure the data that is sent via the script below.

```
{# .twig #}

  Share

```

The default actions to use the SMS and Email services are listed below.

DescriptionActionTwilio Service SMS send action`sms_send`Amazon SES Service email send action`email_send`### Values

[](#values)

NameValue Description`to`A valid email address (validates against the [`FILTER_VALIDATE_EMAIL`](https://www.php.net/manual/en/filter.filters.validate.php) validate filter) or phone number (10 digit number including area code), depending on the action.`action`The Ajax action callback name; `sms_send` or `email_send`.`url`The URL to be shared with the recipient, this is what replaces the contents of the `{{ BITLY_URL }}` and `{{ URL }}` in the post content.`template`The slug of the SMNYC Post to use as the template for sms or email content.`lang`The language code of the template content. This should generally be the same as the current language of the page document. This value is passed to the [`wpml_object_id`](https://wpml.org/wpml-hook/wpml_object_id/) filter provided by [WPML](https://wpml.org/).`hash`Required to prevent [CSRF](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)). The plugin ships with a helper function to generate a new hash value to pass to your view. Below is an example of adding a hash to [Timber context](https://timber.github.io/docs/getting-started/theming/#get-the-context) that is passed to the view template.#### SMNYC\\hash()

[](#smnychash)

```
/* php */

// Retrieving a hash using the SMNYC helper function.
$context['hash'] = SMNYC\hash('https://mysite.com/my-to-share/');
```

Below is an example script that adds a submit event listener to the form, [serializes](https://www.npmjs.com/package/form-serialize) the form data on submit, and passes the data as a JSON object to the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).

```
/* JavaScript */

// https://www.npmjs.com/package/form-serialize
import FormSerialize from 'form-serialize';

let FORM = document.querySelector('[data-js="smnyc"]');

FORM.addEventListener('submit', (event) => {
  // To send the data with the application/x-www-form-urlencoded header
  // we need to use URLSearchParams(); instead of FormData(); which uses
  // multipart/form-data
  let formData = new URLSearchParams();

  // Serialize the form data.
  let data = FormSerialize(FORM, {hash: true});

  // Iterate over our serialized data and append to formData.
  Object.keys(data).map(k => {
    formData.append(k, data[k]);
  });

  // Send the request via the Fetch API.
  fetch(FORM.getAttribute('action'), {
    method: FORM.getAttribute('method'),
    body: formData
  }).then(response => response.json())
    .then(response => {
      // My Response handler
    }).catch(data => {
      // My Error handler
    });
});
```

Response Codes
--------------

[](#response-codes)

Below are various response codes returned by the Email/SMS service and their meaning.

CodesMeaning**General**9The hash provided is invalid. See the [values](#values) table for a description of the `SMNYC\hash()` usage.-1The [configuration](#configuration) is invalid.400A URL is missing from the request. See the [values](#values) table for a full list of required values.**Email**1Missing email address. See the [values](#values) table for a full list of required values.2Invalid email address.3An exception from the Amazon SES service. [Reference the PHP SDK docs](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.Ses.Exception.SesException.html) for error descriptions.**SMS Errors**1Missing phone number. See the [values](#values) table for a full list of required values.2Invalid phone number. Must be a 10-digit number including area code. The final value should be without spaces, dashed, etc.**Twilio Response**30006Unable to send to number provided.21611The outbox queue is full (please try again later).30007Invalid message body.30009Ephemeral errors that a retry might solve....[Reference the Twilio Docs](https://www.twilio.com/docs/sms) for other errors.Actions
-------

[](#actions)

### smnyc\_message\_sent

[](#smnyc_message_sent)

This action is fired after a message is sent successfully.

**...args**

- `String  $type` Email/SMS/whatever the class type is.
- `String  $to` Recipient of message.
- `String  $guid` Session GUID.
- `String  $url` URL to that has been shared.
- `String  $msg` The body of the message.

#### Examples

[](#examples)

```
add_action('smnyc_message_sent', function($type, $to, $uid, $url, $message) {
  // Successful message sent handler
}, 10, 5);
```

---

[![The Mayor's Office for Economic Opportunity Civic Tech](nyco-civic-tech.blue@2x.png)](nyco-civic-tech.blue@2x.png)

[The Mayor's Office for Economic Opportunity](http://nyc.gov/opportunity) is committed to sharing open source software that we use in our products. Feel free to ask questions and share feedback. **Interested in contributing?** See our open positions on [buildwithnyc.github.io](http://buildwithnyc.github.io/). Follow our team on GitHub [@nycopportunity](https://github.com/orgs/NYCOpportunity) and [@cityofnewyork:nycopportunity](https://github.com/orgs/CityOfNewYork/teams/nycopportunity) or [browse our work on Github](https://github.com/search?q=nycopportunity).

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 76.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~42 days

Recently: every ~14 days

Total

22

Last Release

1475d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a772d4b08a51649d663a68fb04b475b0c50cd6b7b0a8d74d8fa922ab69ee8945?d=identicon)[nycopportunity](/maintainers/nycopportunity)

---

Top Contributors

[![devowhippit](https://avatars.githubusercontent.com/u/3826974?v=4)](https://github.com/devowhippit "devowhippit (26 commits)")[![theasteve](https://avatars.githubusercontent.com/u/14843767?v=4)](https://github.com/theasteve "theasteve (6 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

---

Tags

awsaws-sesbitlyemailmu-pluginnycopportunitypluginservicesmstheme-developmenttimbertwiliowordpresswpmlwordpressawsemailsmstwiliobitlythemesharingintegrationsnycopportunity

###  Code Quality

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/nyco-wp-send-me-nyc/health.svg)

```
[![Health](https://phpackages.com/badges/nyco-wp-send-me-nyc/health.svg)](https://phpackages.com/packages/nyco-wp-send-me-nyc)
```

###  Alternatives

[laravel-notification-channels/twilio

Provides Twilio notification channel for Laravel

2587.7M12](/packages/laravel-notification-channels-twilio)[ferdous/laravel-otp-validate

Laravel package for OTP validation with built-in features like retry and resend mechanism. Built in max retry and max resend blocking. OTP/Security Code can be send over SMS or Email of your choice with user-defined template.

7124.4k](/packages/ferdous-laravel-otp-validate)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)