Nylas PHP SDK (api version 2.3)
This package is auto-updated.
Last update: 2022-11-19 02:02:43 UTC
Last check at the point: Nylas Updates January 7th, 2022 (2022-01-27)
- API 2.3 support
- All Nylas APIs have been implemented within this SDK.
- Support send & get message in raw type
- Support async batch upload & download
-- Contact picture download
-- File upload & download
- The parameters that required by methods almost the same as nylas official api required.
- Support async batch get & delete & send
- Chained calls and good code hints, easy to use
version 3.x for php >= 7.3 (branch 3.0)
version 4.x for php >= 7.4 (branch 4.0)
version 5.x for php >= 8.0 (branch master)
Tips: There are many breaking changes since version 5.0
- all methods name changed (named same as the nylas API doc describe title)
- the smart methods removed
- many other changes
This library is available on https://packagist.org/packages/lanlin/nylas-php
You can install it by running
composer require lanlin/nylas-php
Before you can interact with the Nylas REST API,
you need to create a Nylas developer account at https://www.nylas.com/.
After you've created a developer account, you can create a new application to generate an App ID / Secret pair.
Generally, you should store your App ID and Secret into environment variables to avoid adding them to source control.
The test projects use configuration files instead, to make it easier to get started.
use Nylas\Client; $options = [ 'client_id' => 'your client id', // required 'client_secret' => 'your client secret' // required 'debug' => true, 'region' => 'us', // server region, can be us, ireland or canada, default is us 'log_file' => dirname(__FILE__) . '/test.log', // a file path or a resource handler 'access_token' => 'your access token', ]; $nylas = new Client($options);
You can modify options with methods of
Most of the methods that have the get & delete prefix support batch request.
$id = 'id_xxx'; $ids = ['id_xxx', 'id_yyy', ...]; // one per time $dataA = $nylas->Contacts->Contact->returnAContact($id); $dataB = $nylas->Contacts->Contact->deleteAContact($id); // batch request $dataC = $nylas->Contacts->Contact->returnAContact($ids); $dataD = $nylas->Contacts->Contact->deleteAContact($ids);
For more detail about the batch request, you should have to read the source code.
Sorry, I have no time to write documents.
There are two ways you can authenticate users to your application.
Hosted & Native are both supported.
For Native Authentication example, please visit Native Auth Document
For Hosted OAuth(server-side three-legged) example:
- You redirect the user to nylas login page, along with your App Id and Secret
- Your user logs in
- She is redirected to a callback URL of your own, along with an access code
- You use this access code to get an authorization token to the API
For more information about authenticating with Nylas,
visit the Developer Documentation.
In practice, the Nylas REST API client simplifies this down to two steps.
Step 1: Redirect the user to Nylas:
$params = [ 'state' => 'testing', 'login_hint' => 'email@example.com', 'redirect_uri' => 'https://www.test.com/redirect_callback', ]; // generate the url that your user need be redirect to. $url = $nylas->Authentication->Hosted->authenticateUser($params);
Step 2: your user logs in:
Step 3: you got the access code from the nylas callback:
Please implement the above 2 & 3 steps yourself.
Step 4: Get authorization token with access code:
$data = $nylas->Authentication->Hosted->sendAuthorizationCode($params); // save your token some where // or update the client option $nylas->Options->setAccessToken("pass the token you got");
common error codes that response from nylas are wrapped as exceptions, (see
src/Exceptions) and the exception code is the same as nylas api error list
you will get an array like below, when response data was not a valid json string or even not json content type:
[ 'httpStatus' => 'http status code', 'invalidJson' => true, 'contentType' => 'response header content type', 'contentBody' => 'response body content', ]
for all methods that execute as the async mode will not throw an exception when an error occurs, instead, it will return an array which contains all data and exceptions inside like below:
[ // ... [ 'error' => true, 'code' => 'exception code', 'message' => 'exception message', 'exception' => 'exception instance', ], // ... ]
some email provider may not support all features, exp: calendar, event. for that reason you may get an exception named
BadRequestExceptionwith 400 code and the msg:
Malformed or missing a required parameter, or your email provider not support this.
log_fileparameter only works when
true, then the detailed info of the http request will be logged.
Tips: nylas-php use the guzzlehttp for http request. but guzzlehttp only support a resource type as the debug handler (cURL CURLOPT_STDERR required that).
for anyone who wants to use psr/log interface to debug, you can init a temp resource, and pass the handler to nylas-php, then get log content from temp resource after calling some methods.
$handler = fopen('php://temp', 'w+'); $options = [ 'log_file' => $handler, ... ]; $nylas = new Client($options); $nylas->doSomething(); .... rewind($handler); $logContent = stream_get_contents($handler); fclose($handler); $yourPsrLogger->debug($logContent);
- Initialise composer dependency
- Add your info in
- Launch the test with
composer run-script test
- Another way to run tests:
./tests/do.sh foo.php --filter fooMethod, see
Each method's comment has a link to their specific API document, see here
The parameters that required by methods almost the same as nylas official api required.
For more detail, you can view the tests or the source code of validation rules for that method.
For more usage demos, please view the tests.
Please feel free to use it and send me a pull request if you fix anything or add a feature, though.
This project is licensed under the MIT license.