Version:
Only show these results:

Nylas v2 webhook schemas

This page provides schema references for the webhook notifications that Nylas v2 sends.

Keep in mind

  • The attributes and metadata sub-objects are included in all v2 webhook notifications, but are populated for Message webhooks only. In all other cases, they are null.
  • The namespace_id sub-object is deprecated and has been replaced by account_id, but is included in webhook notifications. You can disregard it.

Account webhook notifications

You can subscribe to the following Account webhook triggers to be notified when changes are made:

  • account.running
  • account.stopped
  • account.invalid
  • account.connected
  • account.sync_error

The following JSON snippet is an example of an Account webhook notification.

{
	"deltas": [{
		"date": 1601672445,
		"object": "account",
		"type": "account.running",
		"object_data": {
			"namespace_id": "cg9razhjs80zqtoz50rox2n6z",
			"account_id": "cg9razhjs80zqtoz50rox2n6z",
			"object": "account",
			"attributes": null,
			"id": "cg9razhjs80zqtoz50rox2n6z",
			"metadata": null
		}
	}]
}

Calendar webhook notifications

You can subscribe to the following Calendar webhook triggers to be notified when changes are made:

Calendar Updated notifications

Nylas sends a calendar.updated notification when an end user updates a calendar or its parameters. See the Calendar reference documentation for more information about the parameters.

{
  "deltas": [{
    "object": "calendar",
    "type": "calendar.updated",
    "source": "/google/events/realtime",
    "id": "FUuYVEHL5gJxB85oKoNxt74890",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "calendar",
      "attributes": null,
      "id": "2x6fbv82cctfjqtzex0aqll96",
      "metadata": null
    }
  }]
}

Event webhook notifications

You can subscribe to the following Event webhook triggers to be notified when changes are made:

Event Created notifications

Nylas sends an event.created notification when an event is created on an end user's calendar.

{
  "deltas": [{
    "object": "event",
    "type": "event.created",
    "source": "/google/events/incremental",
    "id": "hcy2Qzs7yLKhBabtqGEfrX0658",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "d52ehgbft5x3pevzgnmhwumbs",
      "account_id": "d52ehgbft5x3pevzgnmhwumbs",
      "object": "event",
      "attributes": null,
      "id": "bvpgob33f3hvebfuvfndv2cvg",
      "metadata": null
    }
  }]
}

Event Updated notifications

Nylas sends an event.updated notification when an event is cancelled or deleted from an end user's calendar, or when changes are made to the event's parameters. For more information about the parameters, see the v2 Events reference documentation.

{
  "deltas": [{
    "object": "event",
    "type": "event.updated",
    "id": "hcy2Qzs7yLKhBabtqGEfrX0658",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "d52ehgbft5x3pevzgnmhwumbs",
      "account_id": "d52ehgbft5x3pevzgnmhwumbs",
      "object": "event",
      "attributes": null,
      "id": "bvpgob33f3hvebfuvfndv2cvg",
      "metadata": null
    }
  }]
}

Event Deleted notifications

Nylas sends event.deleted notifications only when a syncback request fails. A failure can take a long time to come through, so Nylas recommends you use the event.updated webhook to track these events instead.

{
  "deltas": [{
    "object": "event",
    "type": "event.deleted",
    "id": "hcy2Qzs7yLKhBabtqGEfrX0658",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "d52ehgbft5x3pevzgnmhwumbs",
      "account_id": "d52ehgbft5x3pevzgnmhwumbs",
      "object": "event",
      "attributes": null,
      "id": "bvpgob33f3hvebfuvfndv2cvg",
      "metadata": null
    }
  }]
}

Message webhook notifications

You can subscribe to the following Message webhook triggers to be notified when changes are made:

Message Created notifications

Nylas sends a message.created notification when an end user creates an email message. See the Messages reference documentation for more information.

{
  "deltas": [{
    "object": "message",
    "type": "message.created",
    "source": "/google/emails/incremental",
    "id": "sJ9YV94hiMxrC3jUKZY6v83621",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "message",
      "attributes": {
        "thread_id": "2u152dt4tnq9j61j8seg26ni6",
        "received_date": 1602623166
      },
      "id": "93mgpjynqqu5fohl2dvv6ray7",
      "metadata": null
    }
  }]
}

Message Updated notifications

Nylas sends a message.updated notification when an email message is archived, its label or folder is changed, or changes are made to its parameters. See the Messages reference documentation for more information.

{
  "deltas": [{
    "object": "message",
    "type": "message.updated",
    "id": "hcy2Qzs7yLKhBabtqGEfrX0658",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "message",
      "attributes": { "thread_id": "81nij9mkaueoujxtlprbwfhdx" },
      "id": "bvpgob33f3hvebfuvfndv2cvg",
      "metadata": null
    }
  }]
}

Message Deleted notifications

Nylas sends a message.deleted notification when an email message is deleted. See the Messages reference documentation for more information.

{
  "deltas": [{
    "object": "message",
    "type": "message.deleted",
    "id": "hcy2Qzs7yLKhBabtqGEfrX0658",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "message",
      "attributes": { "thread_id": "81nij9mkaueoujxtlprbwfhdx" },
      "id": "bvpgob33f3hvebfuvfndv2cvg",
      "metadata": null
    }
  }]
}

Message tracking webhook notifications

You can subscribe to the following webhook triggers to be notified when a tracking trigger is fulfilled on email messages with tracking enabled:

See the message tracking documentation for more information.

Message Opened notifications

Nylas sends a message.opened notification when a participant first opens a tracked email message.

{
  "deltas": [{
    "object": "metadata",
    "type": "message.opened",
    "id": "hcy2Qzs7yLKhBabtqGEfrX0658",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "metadata",
      "attributes": null,
      "id": "bvpgob33f3hvebfuvfndv2cvg",
      "metadata": {
        "count": 1,
        "timestamp": 1711970842,
        "recents": [{
          "ip": "66.149.83.102, 10.158.62.17", 
          "user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)", 
          "id": 0, 
          "timestamp": 1711970842
        }],
        "message_id": "cesx0dicjo9nv1h1401ct8gxq",
        "payload": "new-payload"
      }
    }
  }]
}

Nylas sends a message.link_clicked notification when a participant clicks a link in a tracked email message.

{
  "deltas": [{
    "object": "metadata",
    "type": "message.link_clicked",
    "id": "hcy2Qzs7yLKhBabtqGEfrX0658",
    "time": 1602623196,
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "metadata",
      "attributes": null,
      "id": "bvpgob33f3hvebfuvfndv2cvg",
      "metadata": {
        "link_data": [{
          "url": "https://nylas.com",
          "count": 1
        }],
        "timestamp": 1711973038,
        "recents": [{
          "ip": "2207:fea6:bb1b:f060:90a3:ff5d:5c0e:2f26, 10.158.39.146",
          "link_index": 0,
          "id": 0,
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
          "timestamp": 1711973076
        }],
        "message_id": "cav87twpqacuscbvi5sdx2rb8",
        "payload": "new-payload"
      }
    }
  }]
}

Thread Replied notifications

Nylas sends a thread.replied notification when a participant replies to a tracked email thread.

{
  "deltas": [{
    "date": 1471630848,
    "type": "thread.replied",
    "object": "metadata",
    "object_data": {
      "object": "metadata",
      "id": "<METADATA_ID>",
      "account_id": "<NYLAS_ACCOUNT_ID>",
      "metadata": {
        "sender_app_id": "<SENDER_APP_ID>",
        "payload": "{myCustom: 'data'}",
        "message_id": "<NYLAS_MESSAGE_ID>",
        "reply_to_message_id": "<NYLAS_MESSAGE_ID>",
        "thread_id": "<NYLAS_THREAD_ID>",
        "from_self": true,
        "timestamp": 1471630848
      }
    }
  }]
}

Contact webhook notifications

You can subscribe to the following Contact webhook triggers to be notified when changes are made:

Contact Created notifications

Nylas sends a contact.created notification when an end user creates a contact. For more information, see the Contacts reference documentation.

{
  "deltas": [{
    "date": 1601667544,
    "object": "contact",
    "type": "contact.created",
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "contact",
      "attributes": null,
      "id": "1iacfgi0qcm28734iusgzo20o",
      "metadata": null
    }
  }]
}

Contact Updated notifications

Nylas sends a contact.updated notification when changes are made to one or more of a contact's parameters. For more information about these parameters, see the Contacts reference documentation.

{
  "deltas": [{
    "date": 1601667544,
    "object": "contact",
    "type": "contact.updated",
    "object_data": {
      "namespace_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "account_id": "aaz875kwuvxik6ku7pwkqp3ah",
      "object": "contact",
      "attributes": null,
      "id": "1iacfgi0qcm28734iusgzo20o",
      "metadata": null
    }
  }]
}

Job status notifications

You can subscribe to the following webhook triggers to be notified when a job's status changes:

  • job.successful
  • job.failed

The following JSON snippet is an example of a job status webhook notification.

{
  "deltas": [{
    "date": 1646346704,
    "object": "job_status",
    "type": "job.failed",
    "object_data": {
      "namespace_id": "cL1PMVLIa1QXtg2HKKnuHhgxsy",
      "account_id": "cL1PMVLIa1QXtg2HKKnuHhgxsy",
      "object": "message",
      "attributes": {
        "action": "update_message",
        "thread_id": null,
        "extras": {
          "reason": "error updating message",
          "original_send_at": 1646346692,
          "send_at": 1646346692
        },
        "message_id": null,
        "job_status_id": "fKZwgtxkb4mphQSIhOxL8OmS2G"
      },
      "id": null,
      "metadata": null
    }
  }]
}