Creating Events

Learn how to create calendar events with all available options.

Basic Event

The minimum required fields are title, startTime, and endTime:

curl -X POST https://solomail.io/api/v1/calendar/events \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Quick Meeting",
    "startTime": "2026-01-20T14:00:00Z",
    "endTime": "2026-01-20T14:30:00Z"
  }'

Event with Timezone

Always specify a timezone for accurate display across different calendars:

{
  "title": "Team Standup",
  "startTime": "2026-01-20T09:00:00-05:00",
  "endTime": "2026-01-20T09:30:00-05:00",
  "timezone": "America/New_York"
}

Supported Timezones: Any valid IANA timezone identifier (e.g., America/New_York, Europe/London, Asia/Tokyo)

All-Day Events

For events that span entire days:

{
  "title": "Company Retreat",
  "startTime": "2026-01-20T00:00:00Z",
  "endTime": "2026-01-22T00:00:00Z",
  "allDay": true
}

Event with Location

Physical Location

{
  "title": "Client Meeting",
  "startTime": "2026-01-20T10:00:00Z",
  "endTime": "2026-01-20T11:00:00Z",
  "location": "123 Main Street, Suite 100, New York, NY 10001"
}

Virtual Meeting

{
  "title": "Remote Standup",
  "startTime": "2026-01-20T09:00:00Z",
  "endTime": "2026-01-20T09:30:00Z",
  "virtualMeeting": {
    "provider": "zoom",
    "url": "https://zoom.us/j/123456789",
    "password": "abc123"
  }
}

Supported Providers:

  • zoom - Zoom Meetings
  • google_meet - Google Meet
  • teams - Microsoft Teams
  • custom - Any other video platform

Recurring Events

Create events that repeat on a schedule:

{
  "title": "Weekly Team Sync",
  "startTime": "2026-01-20T10:00:00Z",
  "endTime": "2026-01-20T11:00:00Z",
  "recurrence": "weekly",
  "recurrenceEndDate": "2026-06-01T00:00:00Z"
}

Recurrence Options:

  • none - One-time event (default)
  • daily - Every day
  • weekly - Every week
  • biweekly - Every two weeks
  • monthly - Every month
  • yearly - Every year

Event with Invitees

Add invitees to send calendar invitations:

{
  "title": "Project Kickoff",
  "startTime": "2026-01-20T14:00:00Z",
  "endTime": "2026-01-20T15:00:00Z",
  "sendEmailReminders": true,
  "invitees": [
    { 
      "email": "john@example.com", 
      "name": "John Doe",
      "isOptional": false 
    },
    { 
      "email": "jane@example.com", 
      "name": "Jane Smith",
      "isOptional": true 
    }
  ]
}

Important: Set sendEmailReminders: true to send invitation emails. Without this, invitees are added but not notified.

Event with Agent

Associate an event with a specific agent for branded communications:

{
  "title": "Support Follow-up Call",
  "startTime": "2026-01-20T15:00:00Z",
  "endTime": "2026-01-20T15:30:00Z",
  "agentId": "agent-uuid-here",
  "sendEmailReminders": true,
  "invitees": [
    { "email": "customer@example.com", "name": "Customer Name" }
  ]
}

When an agent is specified:

  • Invitation emails include the agent's signature
  • The "From" name uses the agent's configured format
  • Events appear in agent activity tracking

Event Colors

Organize events visually with colors:

{
  "title": "Important Deadline",
  "startTime": "2026-01-20T00:00:00Z",
  "endTime": "2026-01-20T23:59:59Z",
  "allDay": true,
  "color": "red"
}

Available Colors: blue, green, red, purple, orange

Reminders

Configure when to send reminder notifications:

{
  "title": "Project Review",
  "startTime": "2026-01-20T14:00:00Z",
  "endTime": "2026-01-20T15:00:00Z",
  "reminders": [
    { "type": "email", "value": 15, "unit": "minutes" },
    { "type": "email", "value": 1, "unit": "hours" },
    { "type": "email", "value": 1, "unit": "days" }
  ]
}

Reminder Units: minutes, hours, days

Complete Example

Here's a fully-featured event:

{
  "title": "Quarterly Business Review",
  "description": "Review Q1 performance metrics and plan Q2 initiatives.",
  "startTime": "2026-01-20T14:00:00-05:00",
  "endTime": "2026-01-20T16:00:00-05:00",
  "timezone": "America/New_York",
  "allDay": false,
  "location": "Main Conference Room",
  "virtualMeeting": {
    "provider": "zoom",
    "url": "https://zoom.us/j/123456789",
    "password": "qbr2026"
  },
  "color": "blue",
  "recurrence": "none",
  "agentId": "scheduling-agent-uuid",
  "sendEmailReminders": true,
  "reminders": [
    { "type": "email", "value": 1, "unit": "days" },
    { "type": "email", "value": 1, "unit": "hours" }
  ],
  "invitees": [
    { "email": "ceo@company.com", "name": "CEO", "isOptional": false },
    { "email": "cfo@company.com", "name": "CFO", "isOptional": false },
    { "email": "marketing@company.com", "name": "Marketing Lead", "isOptional": true }
  ]
}

Next: Learn about Managing Invitees