dánwòdánwò

Connectors

Nylas

Nylas v3 hosted auth and grants, email, calendars and events, contacts and the scheduler, with signed webhooks and mail a test can deliver.

danwo's Nylas emulator answers api.us.nylas.com and api.eu.nylas.com. The nylas package works against it unchanged: your app connects a user's mailbox with hosted auth, then reads and sends mail and events through the grant.

Set up

Add nylasService with your API key and a connected grant:

danwo.config.ts
import { appEnvironment, defineConfig, nylasService } from "@danwo/sdk"

const url = "http://localhost:3000"
const apiKey = "nyk_danwo"

export default defineConfig({
  testDir: "tests",
  readiness: { mode: "page+backend", settle: true },
  environment: () =>
    appEnvironment({
      app: { command: "npm run dev", url, env: { NYLAS_API_KEY: apiKey } },
      services: [
        nylasService({
          seed: {
            apiKeys: [apiKey],
            grants: [
              {
                email: "ada@example.com",
                provider: "google",
                messages: [{ from: "bob@example.com", subject: "Lunch on Friday?" }],
              },
            ],
            webhooks: [{ url: `${url}/api/webhooks/nylas`, triggers: ["message.created"] }],
          },
        }),
      ],
    }),
})

Without apiKeys, any nyk_ key is accepted.

Seed it

FieldWhat it seeds
applicationIdThe application id tokens and notifications carry.
apiKeysThe keys the application accepts.
grantsConnected accounts by email, with their provider, scopes, messages, events and contacts.
webhooksWebhook subscriptions, their triggers, and the secret that signs them.

Use it in a test

Deliver an email to the user, as if someone wrote in, then check the app's reply went out:

tests/auto-reply.danwo.ts
import { type NylasFixtures, nylasApplication, test as base } from "@danwo/sdk"

const test = base.extend<NylasFixtures>()

test("replies to a new booking request", async ({ expect, settle, nylas }) => {
  const application = nylasApplication(nylas)

  application.receive("ada@example.com", {
    from: "bob@example.com",
    subject: "Can we book a call?",
  })
  await settle()

  const [reply] = application.sent("ada@example.com")

  expect(reply?.subject).toBe("Re: Can we book a call?")
})
nylasApplication(nylas)What it's for
grants(), grant(email)The connected accounts.
messages(email), sent(email)A grant's mail, and what it sent.
events(email)A grant's events.
receive(to, mail)Deliver an email, as if someone wrote in.
expire(email)Expire a grant, as when the user's provider token is revoked.

Mail sent between two seeded grants lands in the other's inbox.

What's covered

AreaCovered
AuthHosted auth, consent, token exchange and revoke; grants.
EmailMessages, sending, threads, drafts, folders and attachments.
CalendarCalendars, events and free/busy.
ContactsContacts.
SchedulerConfigurations, availability and bookings.
WebhooksSubscriptions, and rotating their secret.

Faults

CallFaults the matrix tries
POST …/messages/send429, 401, 504, a 30-second delay, 500, connection reset, answer lost after Nylas sent it
A read429, 500, connection reset
Every webhook deliveryarrives twice, arrives 10 minutes late, forged signature, 1 hour stale

Webhooks

Notifications carry X-Nylas-Signature, an HMAC of the body with the subscription's secret.

TriggersSent when
message.*, thread.repliedMail arrives, changes, or gets a reply.
event.*An event is created, updated or deleted.
grant.*A grant is created, updated, expires or is deleted.
contact.*, calendar.*, folder.createdContacts, calendars and folders change.
booking.*A booking is made, rescheduled or cancelled.

Fidelity

Live, reads only. danwo fidelity nylas runs 2 scenarios against a real application: errors, and listing and reading grants. Both match.

Not covered yet

  • Notetaker
  • The Scheduler's hosted booking pages
  • Smart Compose and other AI features

Next

On this page

Run it on every pull request

A GitHub check and one comment per pull request, with the flight records attached.

Set up CI