An automation in ChatGPT can start on its own when new mail arrives in a Shipmail mailbox, a send bounces, a reply is overdue, a conversation needs action, a meeting is about to start, an event starts, ends or changes, a guest replies, someone books a time, someone joins an audience, a newsletter finishes sending, or a domain or your sending reputation needs attention. Shipmail sends ChatGPT an event for each match, and ChatGPT acts with the permissions the connection already has. ChatGPT is the only client that supports MCP events today.
Last updated
How events work
The Shipmail MCP server lists the events it offers. An automation subscribes to one, with filters such as a mailbox or a sender domain. When something matches, Shipmail posts a signed event to ChatGPT, and ChatGPT runs the automation. An event carries metadata only. To read the message, the automation calls a Shipmail tool.
Events follow the connection's permissions. Mail events need permission to read mail, calendar events need permission to read the calendar, booking.created needs permission to read booking pages, subscriber.added needs permission to read audiences, newsletter.sent needs permission to read newsletters, and domain and reputation events need permission to read domains. Every event respects the connection's mailbox, domain and audience limits. Shipmail checks them again before each delivery, so narrowing a connection also narrows its automations.
Domain and reputation events are only for organization Owners and Admins. A Member's connection can't subscribe to them, and an automation stops getting them if the person who made it loses the role. An organization API key with permission to read domains can subscribe too.
Use the Chat/Work switch above the composer. Event automations only exist in Work mode, not in Chat mode.
Describe the automation
For example: "When mail from acme.com arrives at hello@yourdomain.com, draft a reply." ChatGPT picks the event and its filters. To see what Shipmail offers, open the plugin's Tools and events dialog.
The automation then shows on the connection's page in Shipmail, under Developer, Connections.
Event catalogue
message.received
New mail arrived in a mailbox. Automatic mail and spam are left out (see Loop protection).
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
from
Only mail from this exact address.
from_domain
Only mail from senders at this domain, such as acme.com.
to
Only mail delivered to this address, including an alias or catch-all address missing from the To header.
include_bulk
Also send newsletters and mailing-list mail.
Payload field
Meaning
organization_id, mailbox_id
The organization and mailbox the mail belongs to.
mailbox_address
The mailbox's email address.
subject
Written by the sender. Untrusted.
to, cc
Recipients, at most 50 each, with to_count and cc_count.
url
Opens the message in Shipmail.
message_id
Pass it with mailbox_id to shipmail_get_mailbox_inbox_message to read the body.
conversation_id
The conversation (thd_...), when known.
from
The sender's address and name. Untrusted.
received_at
When the message arrived.
authentication
SPF, DKIM and DMARC results.
is_spam
Whether Shipmail classified the message as spam.
message.bounced
A message sent from a mailbox bounced.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
Payload field
Meaning
organization_id, mailbox_id
The organization and mailbox the mail belongs to.
mailbox_address
The mailbox's email address.
subject
Written by the sender. Untrusted.
to, cc
Recipients, at most 50 each, with to_count and cc_count.
url
Opens the message in Shipmail.
message_id
The sent message (msg_...). Pass it to shipmail_get_message.
bounce_type
permanent, transient or undetermined.
bounced_recipients
The addresses that bounced, at most 50, with bounced_recipient_count.
sent_at, bounced_at
When it was sent and when it bounced.
reply.overdue
A conversation in Waiting got no reply after_days after your last tracked send. It fires once per waiting period: a reply, a new send or clearing Waiting starts over.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
after_days
Days without a reply, from 1 to 30. Defaults to 3.
Payload field
Meaning
organization_id, mailbox_id
The organization and mailbox the conversation belongs to.
mailbox_address
The mailbox's email address.
conversation_id
The conversation (thd_...). Pass it as thread_id to shipmail_get_mailbox_inbox_thread.
subject
Written by the other party. Untrusted.
url
Opens the conversation in Shipmail.
message_id
The send you are waiting on (msg_...). Pass it to shipmail_get_message.
waiting_on
To recipients of that send, at most 50, with waiting_on_count.
waiting_since, overdue_at, after_days
When the send went out, when it became overdue, and the days chosen.
conversation.needs_action
A conversation moved to Needs action, because someone replied to a conversation you were waiting on or because a follow-up you set came due. Shipmail checks every minute.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
Payload field
Meaning
organization_id, mailbox_id
The organization and mailbox the conversation belongs to.
mailbox_address
The mailbox's email address.
conversation_id
The conversation (thd_...). Pass it as thread_id to shipmail_get_mailbox_inbox_thread.
subject
Written by the other party. Untrusted.
url
Opens the conversation in Shipmail.
reason
reply_received or follow_up_due.
message_id
For a reply, pass it with mailbox_id to shipmail_get_mailbox_inbox_message. Null for a follow-up.
from
The latest sender's address. Untrusted.
entered_at
When it moved to Needs action.
calendar.event_starting
A reminder that a calendar event starts in minutes_before minutes, not the start itself: use calendar.event_started for that. It arrives up to 6 minutes early and at most 2 minutes late, once per occurrence. Cancelled and all-day events are left out. Needs permission to read the calendar.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_id
Only events in this calendar.
minutes_before
How long before the start, from 5 to 1440 minutes. Defaults to 15.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_at
When the event starts and ends.
url
Opens the event in Shipmail.
title
The event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, recurrence_id
The calendar, and which occurrence of a recurring event.
uid
The event's iCalendar UID, or null. Match it, with recurrence_id, to the event's change events.
time_zone, minutes_before
The event's time zone and the lead time.
scheduled_at
When the reminder was due: the start minus the lead time.
calendar.event_started
A calendar event reached its start. It arrives up to 6 minutes early and at most 2 minutes late, once per occurrence. Cancelled and all-day events are left out. Needs permission to read the calendar.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_id
Only events in this calendar.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_at
When the event starts and ends.
url
Opens the event in Shipmail.
title
The event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, recurrence_id
The calendar, and which occurrence of a recurring event.
uid
The event's iCalendar UID, or null. Match it, with recurrence_id, to the event's change events.
time_zone
The event's time zone.
scheduled_at
When it was due. Compare it with when it arrives to measure the delay.
calendar.event_ended
A calendar event reached its end. An event with no end is left out. It arrives up to 6 minutes early and at most 2 minutes late, once per occurrence. Cancelled and all-day events are left out. Needs permission to read the calendar.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_id
Only events in this calendar.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_at
When the event starts and ends.
url
Opens the event in Shipmail.
title
The event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, recurrence_id
The calendar, and which occurrence of a recurring event.
uid
The event's iCalendar UID, or null. Match it, with recurrence_id, to the event's change events.
time_zone
The event's time zone.
scheduled_at
When it was due. Compare it with when it arrives to measure the delay.
calendar.event_created
An event was added to a calendar, by anyone: Shipmail, a booking, an accepted invitation or a calendar app. It arrives within about 5 minutes, once for a whole repeating series. Needs permission to read the calendar.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_id
Only events in this calendar.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_at
When the event starts and ends.
url
Opens the event in Shipmail.
title
The event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uid
The calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurring
recurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zone
The event's time zone.
detected_at
When Shipmail noticed the change.
operation_key
The operation_key of your own Shipmail API call that made this change, so you can skip your own writes. Null otherwise.
calendar.event_updated
A calendar event changed. A cancellation sends calendar.event_cancelled instead, and a guest's reply sends calendar.rsvp_updated. It arrives within about 5 minutes, once for a whole repeating series. Needs permission to read the calendar.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_id
Only events in this calendar.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_at
When the event starts and ends.
url
Opens the event in Shipmail.
title
The event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uid
The calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurring
recurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zone
The event's time zone.
detected_at
When Shipmail noticed the change.
operation_key
The operation_key of your own Shipmail API call that made this change, so you can skip your own writes. Null otherwise.
changed_fields
What changed: title, starts_at, ends_at, time_zone, location, virtual_location, description, status, recurrence_rule, occurrences or attendees.
previous
The old value of each changed field, except description, attendees and occurrences.
calendar.event_cancelled
A calendar event was cancelled or deleted. No start or end event follows. It arrives within about 5 minutes, once for a whole repeating series. Needs permission to read the calendar.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_id
Only events in this calendar.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_at
When the event starts and ends.
url
Opens the event in Shipmail.
title
The event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uid
The calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurring
recurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zone
The event's time zone.
detected_at
When Shipmail noticed the change.
operation_key
The operation_key of your own Shipmail API call that made this change, so you can skip your own writes. Null otherwise.
reason
cancelled or deleted.
calendar.rsvp_updated
A guest answered an invitation or changed their answer. One event per guest. It arrives within about 5 minutes, once for a whole repeating series. Needs permission to read the calendar.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_id
Only events in this calendar.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_at
When the event starts and ends.
url
Opens the event in Shipmail.
title
The event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uid
The calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurring
recurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zone
The event's time zone.
detected_at
When Shipmail noticed the change.
operation_key
The operation_key of your own Shipmail API call that made this change, so you can skip your own writes. Null otherwise.
attendee_email, attendee_name
The guest's address, and their name as they wrote it. Untrusted.
status, previous_status
accepted, declined, tentative, needs-action or delegated. previous_status is null for a guest added with an answer already given.
booking.created
Someone booked a time through one of your booking pages. Needs permission to read booking pages.
Filter
Meaning
mailbox_id
Only this mailbox. Leave it out to cover every mailbox the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
booking_page_id
Only bookings through this booking page.
Payload field
Meaning
organization_id, mailbox_id
The organization and the mailbox whose calendar it is.
mailbox_address
The mailbox's address. Pass it as mailbox to the calendar tools.
event_id
The calendar event. Pass it with mailbox to shipmail_get_calendar_event.
The booking page or one-off link. booking_page_kind is page or one_off. Pass a page id to shipmail_get_booking_page and a one_off id to shipmail_get_booking_link.
booker
Who booked: their address and name, as typed. Untrusted.
answers
The booker's answers to the page's questions: question_id, label and value, in the page's order. Untrusted.
duration_minutes, time_zone
The meeting's length and the booking page's time zone.
domain.verification_failed
A domain's DNS check failed while it was being set up. Owners and Admins only.
Filter
Meaning
domain_id
Only this domain. Leave it out to cover every domain the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one.
Payload field
Meaning
organization_id
The organization the domain belongs to.
domain_id
Pass it as id to shipmail_get_domain.
domain_name
The domain, such as acme.com.
url
Opens the domain in Shipmail.
records
mx, spf, dkim and dmarc, each true when the record was correct.
checked_at
When the check ran.
domain.degraded
A verified domain's DNS records stopped passing the health check, so its mail may not be delivered. Owners and Admins only.
Filter
Meaning
domain_id
Only this domain. Leave it out to cover every domain the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one.
Payload field
Meaning
organization_id
The organization the domain belongs to.
domain_id
Pass it as id to shipmail_get_domain.
domain_name
The domain, such as acme.com.
url
Opens the domain in Shipmail.
failed_records
The records that failed: mx, spf, dkim, dmarc or ses.
degraded_at
When the check failed.
org.reputation_warning
Deprecated, no longer sent. You can still subscribe to it, but Shipmail no longer has a warning step.
Filter
Meaning
organization_id
The organization to watch. Needed when the connection covers more than one.
Payload field
Meaning
organization_id
The organization.
previous_status, new_status
The sending status before and after: healthy, throttled (slowed down) or suspended (paused). An older event may show warning.
statistics
window_days; total_sent, hard_bounces and complaints as recipient counts; and bounce_rate and complaint_rate per recipient, as fractions.
url
Opens sending reputation in Shipmail.
org.sending_throttled
Shipmail slowed down your sending because too many recipients bounced or reported spam. Owners and Admins only.
Filter
Meaning
organization_id
The organization to watch. Needed when the connection covers more than one.
Payload field
Meaning
organization_id
The organization.
previous_status, new_status
The sending status before and after: healthy, throttled (slowed down) or suspended (paused). An older event may show warning.
statistics
window_days; total_sent, hard_bounces and complaints as recipient counts; and bounce_rate and complaint_rate per recipient, as fractions.
url
Opens sending reputation in Shipmail.
subscriber.added
Someone joined an audience, through the API, the dashboard or a signup form. When the audience asks new subscribers to confirm, it fires once they confirm. CSV imports and migrations send no event. Needs permission to read audiences.
Filter
Meaning
audience_id
Only this audience. Leave it out to cover every audience the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one.
Payload field
Meaning
organization_id
The organization the audience belongs to.
audience_id, audience_name
The audience. Pass the id to shipmail_get_audience.
subscriber_id
Pass it with audience_id to shipmail_get_subscriber.
email_address
The subscriber's address. Untrusted when source is form.
source
api, dashboard or form.
created_at
When they joined.
url
Opens the audience in Shipmail.
newsletter.sent
A newsletter finished sending. It fires once per newsletter. Needs permission to read newsletters.
Filter
Meaning
audience_id
Only this audience. Leave it out to cover every audience the connection can read.
organization_id
The organization to watch. Needed when the connection covers more than one.
Payload field
Meaning
organization_id
The organization.
newsletter_id
Pass it as id to shipmail_get_newsletter.
subject
Written by your organization.
audience_id
The audience it went to, or null if it was deleted.
How many recipients it had, and how many emails were sent, failed or skipped.
sent_at
When sending finished.
url
Opens the newsletter's report in Shipmail.
Calendar event timing and guarantees
calendar.event_starting is a reminder, not the start. calendar.event_started and calendar.event_ended fire at the start and the end.
These three fire at the moment they are due. Shipmail checks every 5 minutes, so one arrives up to 6 minutes early and at most 2 minutes late. Each carries scheduled_at, the moment it was due, so the automation can measure the delay.
They fire once per occurrence, with recurrence_id set for a repeating event. All-day events get none, and an event with no end gets no calendar.event_ended.
To match a timing event to its change events, compare uid, plus recurrence_id for an occurrence of a repeating event.
An event moved after its reminder fired gets a new reminder for the new time. A cancelled or deleted event fires no later start or end.
calendar.event_created, calendar.event_updated, calendar.event_cancelled and calendar.rsvp_updated arrive within about 5 minutes of the change, whoever made it. A repeating event reports once for the series, with recurrence_id set to null.
calendar.event_updated names what changed in changed_fields and gives the old values in previous, except description, attendees and occurrences. A cancellation sends only calendar.event_cancelled.
A booking sends both booking.created and calendar.event_created.
The first check after an automation subscribes records each calendar as it is and sends nothing. More than 200 changes in one mailbox between two checks, such as an import, are taken in without events.
When the automation changes an event through Shipmail with an operation_key, the change event carries the same key, so the automation can skip its own writes. The key is null when anyone else changed the event before the next check, and for deletes.
A retried delivery carries the same payload and the same event ID.
What an event never contains
No message body, no snippet of it and no attachment names, no event description or booking note (calendar.event_updated only names a changed description), and no newsletter body or subscriber custom fields. The automation reads the body with shipmail_get_mailbox_inbox_message, which marks it as untrusted content. Other people still write the subject, an invitation's title and location, and their own name and address. See untrusted content in events.
Loop protection
An automation that replies to mail could end up trading replies with another auto-responder forever. These rules stop that:
Mail sent from any mailbox in your organization never triggers an event.
Automatic mail never does either: auto-replies, delivery reports, bulk and mailing-list mail, and spam. The include_bulk filter lets newsletters and list mail through.
After 10 events from one sender within an hour, that sender is muted for the automation for 24 hours. Only a sender whose mail passed DMARC is counted by address. Other mail is counted by the domain it claims, so forged mail can never mute the real sender.
Each automation gets at most 500 events in 24 hours.
The connection page shows how many events each automation skipped because of these limits.
How long an automation lasts
A subscription lasts 7 days, and ChatGPT renews it while the automation exists. When you delete the automation in ChatGPT, the subscription expires within 7 days. Shipmail retries a failed delivery. Once 5 deliveries in a row fail for good, the automation shows as failing and gets no more events until ChatGPT renews it.
Stop an automation
In Shipmail, open Developer, Connections, choose the ChatGPT connection, and select Stop next to the automation. Stopping is permanent. To start again, create the automation in ChatGPT. You can also delete the automation in ChatGPT. Removing the connection stops all of its automations at once.