# Smart Invites

Smart Invites are trackable calendar invite files that keep your application up to date with attendee status changes without needing a connection to their calendar. Your application can be notified when an attendee accepts the event or declines it from their calendar.

Healthcare appointments or interviews can then be rescheduled. A rental property viewing or restaurant booking can be auto cancelled and the slot made available to others.

Importantly the workflow decisions are yours but Cronofy gives you the real-time notification you need to trigger the appropriate process at the appropriate time.

If you're already sending invite files from your application then this is a really simple operation to swap out your existing ICS generation with Cronofy Smart Invites.

```mermaid
sequenceDiagram
autonumber

Your Application->>Cronofy: Create a Smart Invite
Cronofy->>Your Application: ICS file


Your Application->>Invitee: Email
Invitee->>Cronofy: Response

Cronofy->>Cronofy: Update status
Cronofy-->>Your Application: Push Notification```
> **WARNING:** **iCloud** calendars do not send responses when a recipient accepts or declines an invite.
This behavior also happens when non-Cronofy invites are sent. iCloud users cannot share attending status with non-iCloud calendars until Apple addresses the underlying issue.
This means that Smart Invites sent to iCloud email addresses will not receive status updates and callback.

Please note that this restriction is because of *iCloud* rather than Apple devices - a Smart Invite accepted on an iPhone into a Google Calendar will still work.

> **WARNING:** Calendar providers do not send responses when a recipient deletes an event on their calendar.
As there is no response to capture from deleting an event, attending status will not be updated and no callback will be sent.

## Creating your first Smart Invite
A single API call is all that's needed to generate the invite you can allow the user to download or send via email.

```http
POST /v1/smart_invites HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "recipient": {
    "email": "cronofy@example.com"
  },
  "smart_invite_id": "your-unique-identifier-for-invite",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": "2026-05-07T09:30:00Z",
    "end": "2026-05-07T10:30:00Z",
    "tzid": "Europe/London",
    "location": {
      "description": "Board room"
    }
  },
  "callback_url": "https://example.com/smart_invite/notifications"
}
```

The key attributes from the above sample request are as follows,

##### `API_KEY`

This is the `client_secret` for your Application in the [Cronofy Developer Dashboard](https://app.cronofy.com/jump/developer).

##### `recipient`

This contains the email address of the attendee.

##### `smart_invite_id`

Your unique identifier for the Smart Invite.

##### `event`

This contains all the fields for the event.

##### `callback_url`

The url for Cronofy to 'POST' updates to whenever the attendee status changes.

Further details on these parameters can be found [here](/developers/api/smart-invites/create-smart-invite/index.md).

```json
{
  "event": {...},
  "attachments": { "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..." }
}
```

## Sending the Smart Invite
**Cronofy does not send the email.**

Different languages and frameworks vary but the process requires creating two attachments on the email message. A Rails Mailer example is given here:

```ruby
class SmartInviteMailer < ActionMailer::Base
  def invite(smart_invite) event_ics = smart_invite.attachments.icalendar

    method = 'REQUEST' # method=CANCEL in the case of cancellations

    attachments.inline["invite.ics"] = {
      content_type: "text/calendar; charset=UTF-8; method=#{method}",
      encoding: '7bit',
      content: event_ics,
    }

    attachments["invite.ics"] = {
      content_type: "application/ics; charset=UTF-8; method=#{method}",
      encoding: 'base64',
      content: Base64.encode64(event_ics),
    }

    mail(
      to: smart_invite.recipient.email,
      subject: "Smart Invite Example",
      body: "Here is your invite."
    )
  end
end
```

You'll note that the invite is added **twice**. Once **inline** as `text/calendar` with `7bit`encoding and once as `application/ics` with `base64` encoding.

Doing this is standards guidance for best practice and ensures the widest compatibility with calendar servers and clients.

Examples for different languages in [Sending Smart Invites](/developers/smart-invites/sending/index.md)

## Tracking Attendee Status
You can request the current status of a Smart Invite by querying the `/v1/smart_invites` API endpoint.

```http
GET /v1/smart_invites?recipient_email=cronofy@example.com&smart_invite_id=your-unique-identifier-for-invite HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
```

You'll receive back the entire information about that invitation including the following attributes.

```json
{
  "recipient": {
    "email": "cronofy@example.com",
    "status": "pending"
  },
  "replies": [
    {
      "email": "person1@example.com",
      "status": "accepted"
    },
    {
      "email": "person2@example.com",
      "status": "declined"
    }
  ],
}
```

##### `recipient`

This is the same as the submission with the addition of a status attribute indicating whether the recipient has accepted or not.

##### `replies`

Is a list of all replies to the invite. This will usually be the same as the recipient but it's presented as a separate attribute because it is possible for other people to reply to the calendar invite. This can be when email aliases are used or when the recipient is a team mailbox that is shared by multiple people.

You can then see at any time, who's accepted, who's declined and make sure your application and thus your user is fully informed.

## Status Update Callbacks
The last concept to cover is the callback. Whenever a reply is received, Cronofy will generate a push notification to the `callback_url` you specified when creating the event. The body will be similar to this:

```json
{
  "notification": {
    "type": "smart_invite"
  },
  "smart_invite": {
    "recipient": {
      "email": "cronofy@example.com",
      "status": "accepted"
    },
    "smart_invite_id": "your-unique-identifier-for-invite",
    "callback_url": "https://example.com/..."
  }
}
```

This is a quick introduction to Smart Invites. If you have any further questions please send us an email at [support@cronofy.com](mailto:support@cronofy.com) or go to [this](/developers/api/smart-invites/create-smart-invite/index.md) page for a more detailed look at creating and updating smart invites.


---
[Read in HTML](/developers/smart-invites/)

## In this section

- [Sending Smart Invites](/developers/smart-invites/sending/index.md) — How to attached Smart Invites to emails to ensure they're automatically added to the recipient's calendar.
- [Custom organizer email](/developers/smart-invites/organizer-email/index.md) — How to configure Smart Invites with a custom organizer email.