​
Request Parameters

The following parameters are used when sending a calendar invite:
ParameterTypeRequiredDescription
sender_addressstringYesEmail address that will appear in the “From” field
recipient_addressstringYesEmail address of the recipient
event_titlestringYesTitle of the calendar event
start_timestringYesStart time of the event in ISO 8601 format (UTC)
end_timestringYesEnd time of the event in ISO 8601 format (UTC)
organizer_namestringYesName of the event organizer
methodstringYesCalendar method (REQUEST, CANCEL, REPLY)
locationstringNoLocation of the event
descriptionstringNoDescription of the event
attendeesarrayNoArray of attendee email addresses
mail_headersobjectNoAdditional email headers (sequence, etc.)

​
Code Examples

​
Send a Basic Calendar Invite

curl --location 'https://api.a1base.com/v1/emails/{account_id}/send-calendar-invite' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Secret: YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sender_address": "[email protected]",
    "recipient_address": "[email protected]",
    "event_title": "Team Meeting",
    "start_time": "2024-06-10T10:00:00Z",
    "end_time": "2024-06-10T11:00:00Z",
    "organizer_name": "Alice Smith",
    "method": "REQUEST"
}'

​
Send a Detailed Calendar Invite

curl --location 'https://api.a1base.com/v1/emails/{account_id}/send-calendar-invite' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Secret: YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sender_address": "[email protected]",
    "recipient_address": "[email protected]",
    "event_title": "Team Meeting",
    "start_time": "2024-06-10T10:00:00Z",
    "end_time": "2024-06-10T11:00:00Z",
    "organizer_name": "Alice Smith",
    "method": "REQUEST",
    "location": "Conference Room 1",
    "description": "Monthly team sync-up",
    "attendees": ["[email protected]", "[email protected]"],
    "mail_headers": {
        "sequence": 0
    }
}'

​
Cancel a Calendar Event

curl --location 'https://api.a1base.com/v1/emails/{account_id}/send-calendar-invite' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Secret: YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
    "sender_address": "[email protected]",
    "recipient_address": "[email protected]",
    "event_title": "Team Meeting",
    "start_time": "2024-06-10T10:00:00Z",
    "end_time": "2024-06-10T11:00:00Z",
    "organizer_name": "Alice Smith",
    "method": "CANCEL",
    "location": "Conference Room 1",
    "description": "Meeting has been cancelled",
    "attendees": ["[email protected]", "[email protected]"],
    "mail_headers": {
        "sequence": 1
    }
}'
We’d love to hear from you!Don’t hesitate to reach out to [email protected] or [email protected] if there’s any features you’d like to see or prioritised!

​
Calendar Invite Methods

The A1Mail API supports different calendar methods for managing events:

​
REQUEST

Used to create new calendar events or invite attendees to an event. This is the most common method for sending calendar invites.

​
CANCEL

Used to cancel an existing calendar event. When using this method, make sure to increment the sequence number in mail_headers to indicate this is an update to the original event.

​
REPLY

Used by attendees to respond to calendar invites (Accept, Decline, Tentative). This method is typically used when building calendar applications that need to handle responses.

​
Time Format Guidelines

All time values should be provided in ISO 8601 format with UTC timezone:
  • Format: YYYY-MM-DDTHH:MM:SSZ
  • Example: 2024-06-10T10:00:00Z
  • Time Zone: Always use UTC (Z suffix)
The recipient’s calendar application will automatically convert times to their local timezone for display.

​
Working with Attendees

When specifying attendees, provide an array of email addresses. The system will automatically:
  • Send calendar invites to all specified attendees
  • Handle RSVP responses if configured
  • Track attendance status for each attendee

​
Understanding Sequence Numbers

The mail_headers field, specifically the sequence attribute, is used in calendar invites to manage updates to events. Here’s how it works:

​
Purpose of Sequence in Calendar Invites

Event Versioning: The sequence number is used to track the version of a calendar event. Each time an event is updated (e.g., time change, location change), the sequence number is incremented. This helps recipients’ calendar applications understand that the event has been modified and that they should update the existing event details with the new information. Conflict Resolution: By using a sequence number, calendar systems can resolve conflicts between different versions of the same event. If a recipient receives multiple updates for the same event, the update with the highest sequence number is considered the most recent and authoritative. Synchronization: It ensures that all participants have the latest version of the event. When an event organizer sends an update, the sequence number helps ensure that all attendees’ calendars are synchronized with the latest event details.

​
How It Works

  • Initial Event: When an event is first created, the sequence number is typically set to 0
  • Event Update: If the event is updated, the sequence number is incremented (e.g., from 0 to 1)
  • Event Cancellation: If the event is canceled, the sequence number is also incremented to indicate a change

​
Example Sequence Flow

  1. Original Event: sequence: 0
  2. First Update: sequence: 1 (e.g., time changed)
  3. Second Update: sequence: 2 (e.g., location changed)
  4. Cancellation: sequence: 3
By using the sequence number, calendar applications can ensure that they are displaying the most current version of an event to users.