Skip to content

MCP serverEvents and automations

MCP events and ChatGPT automations

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.

Start an automation in ChatGPT

  1. Connect Shipmail

    Add Shipmail to ChatGPT as described in Connect an agent.

  2. Switch to Work mode

    Use the Chat/Work switch above the composer. Event automations only exist in Work mode, not in Chat mode.

  3. 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).

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
fromOnly mail from this exact address.
from_domainOnly mail from senders at this domain, such as acme.com.
toOnly mail delivered to this address, including an alias or catch-all address missing from the To header.
include_bulkAlso send newsletters and mailing-list mail.
Payload fieldMeaning
organization_id, mailbox_idThe organization and mailbox the mail belongs to.
mailbox_addressThe mailbox's email address.
subjectWritten by the sender. Untrusted.
to, ccRecipients, at most 50 each, with to_count and cc_count.
urlOpens the message in Shipmail.
message_idPass it with mailbox_id to shipmail_get_mailbox_inbox_message to read the body.
conversation_idThe conversation (thd_...), when known.
fromThe sender's address and name. Untrusted.
received_atWhen the message arrived.
authenticationSPF, DKIM and DMARC results.
is_spamWhether Shipmail classified the message as spam.

message.bounced

A message sent from a mailbox bounced.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
Payload fieldMeaning
organization_id, mailbox_idThe organization and mailbox the mail belongs to.
mailbox_addressThe mailbox's email address.
subjectWritten by the sender. Untrusted.
to, ccRecipients, at most 50 each, with to_count and cc_count.
urlOpens the message in Shipmail.
message_idThe sent message (msg_...). Pass it to shipmail_get_message.
bounce_typepermanent, transient or undetermined.
bounced_recipientsThe addresses that bounced, at most 50, with bounced_recipient_count.
sent_at, bounced_atWhen 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
after_daysDays without a reply, from 1 to 30. Defaults to 3.
Payload fieldMeaning
organization_id, mailbox_idThe organization and mailbox the conversation belongs to.
mailbox_addressThe mailbox's email address.
conversation_idThe conversation (thd_...). Pass it as thread_id to shipmail_get_mailbox_inbox_thread.
subjectWritten by the other party. Untrusted.
urlOpens the conversation in Shipmail.
message_idThe send you are waiting on (msg_...). Pass it to shipmail_get_message.
waiting_onTo recipients of that send, at most 50, with waiting_on_count.
waiting_since, overdue_at, after_daysWhen 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
Payload fieldMeaning
organization_id, mailbox_idThe organization and mailbox the conversation belongs to.
mailbox_addressThe mailbox's email address.
conversation_idThe conversation (thd_...). Pass it as thread_id to shipmail_get_mailbox_inbox_thread.
subjectWritten by the other party. Untrusted.
urlOpens the conversation in Shipmail.
reasonreply_received or follow_up_due.
message_idFor a reply, pass it with mailbox_id to shipmail_get_mailbox_inbox_message. Null for a follow-up.
fromThe latest sender's address. Untrusted.
entered_atWhen 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_idOnly events in this calendar.
minutes_beforeHow long before the start, from 5 to 1440 minutes. Defaults to 15.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
titleThe event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, recurrence_idThe calendar, and which occurrence of a recurring event.
uidThe event's iCalendar UID, or null. Match it, with recurrence_id, to the event's change events.
time_zone, minutes_beforeThe event's time zone and the lead time.
scheduled_atWhen 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_idOnly events in this calendar.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
titleThe event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, recurrence_idThe calendar, and which occurrence of a recurring event.
uidThe event's iCalendar UID, or null. Match it, with recurrence_id, to the event's change events.
time_zoneThe event's time zone.
scheduled_atWhen 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_idOnly events in this calendar.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
titleThe event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, recurrence_idThe calendar, and which occurrence of a recurring event.
uidThe event's iCalendar UID, or null. Match it, with recurrence_id, to the event's change events.
time_zoneThe event's time zone.
scheduled_atWhen 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_idOnly events in this calendar.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
titleThe event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uidThe calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurringrecurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zoneThe event's time zone.
detected_atWhen Shipmail noticed the change.
operation_keyThe 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_idOnly events in this calendar.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
titleThe event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uidThe calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurringrecurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zoneThe event's time zone.
detected_atWhen Shipmail noticed the change.
operation_keyThe operation_key of your own Shipmail API call that made this change, so you can skip your own writes. Null otherwise.
changed_fieldsWhat changed: title, starts_at, ends_at, time_zone, location, virtual_location, description, status, recurrence_rule, occurrences or attendees.
previousThe 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_idOnly events in this calendar.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
titleThe event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uidThe calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurringrecurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zoneThe event's time zone.
detected_atWhen Shipmail noticed the change.
operation_keyThe operation_key of your own Shipmail API call that made this change, so you can skip your own writes. Null otherwise.
reasoncancelled 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
calendar_idOnly events in this calendar.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
titleThe event title. Whoever sent an invitation wrote it. Untrusted.
calendar_id, uidThe calendar, and the event's iCalendar UID, shared by every copy of an invitation.
recurrence_id, is_recurringrecurrence_id is null: a change covers the whole series. is_recurring says whether it repeats.
time_zoneThe event's time zone.
detected_atWhen Shipmail noticed the change.
operation_keyThe operation_key of your own Shipmail API call that made this change, so you can skip your own writes. Null otherwise.
attendee_email, attendee_nameThe guest's address, and their name as they wrote it. Untrusted.
status, previous_statusaccepted, 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.

FilterMeaning
mailbox_idOnly this mailbox. Leave it out to cover every mailbox the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one organization and no mailbox is named.
booking_page_idOnly bookings through this booking page.
Payload fieldMeaning
organization_id, mailbox_idThe organization and the mailbox whose calendar it is.
mailbox_addressThe mailbox's address. Pass it as mailbox to the calendar tools.
event_idThe calendar event. Pass it with mailbox to shipmail_get_calendar_event.
starts_at, ends_atWhen the event starts and ends.
urlOpens the event in Shipmail.
booking_page_id, booking_page_name, booking_page_kindThe 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.
bookerWho booked: their address and name, as typed. Untrusted.
answersThe booker's answers to the page's questions: question_id, label and value, in the page's order. Untrusted.
duration_minutes, time_zoneThe 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.

FilterMeaning
domain_idOnly this domain. Leave it out to cover every domain the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one.
Payload fieldMeaning
organization_idThe organization the domain belongs to.
domain_idPass it as id to shipmail_get_domain.
domain_nameThe domain, such as acme.com.
urlOpens the domain in Shipmail.
recordsmx, spf, dkim and dmarc, each true when the record was correct.
checked_atWhen 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.

FilterMeaning
domain_idOnly this domain. Leave it out to cover every domain the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one.
Payload fieldMeaning
organization_idThe organization the domain belongs to.
domain_idPass it as id to shipmail_get_domain.
domain_nameThe domain, such as acme.com.
urlOpens the domain in Shipmail.
failed_recordsThe records that failed: mx, spf, dkim, dmarc or ses.
degraded_atWhen the check failed.

org.reputation_warning

Deprecated, no longer sent. You can still subscribe to it, but Shipmail no longer has a warning step.

FilterMeaning
organization_idThe organization to watch. Needed when the connection covers more than one.
Payload fieldMeaning
organization_idThe organization.
previous_status, new_statusThe sending status before and after: healthy, throttled (slowed down) or suspended (paused). An older event may show warning.
statisticswindow_days; total_sent, hard_bounces and complaints as recipient counts; and bounce_rate and complaint_rate per recipient, as fractions.
urlOpens sending reputation in Shipmail.

org.sending_throttled

Shipmail slowed down your sending because too many recipients bounced or reported spam. Owners and Admins only.

FilterMeaning
organization_idThe organization to watch. Needed when the connection covers more than one.
Payload fieldMeaning
organization_idThe organization.
previous_status, new_statusThe sending status before and after: healthy, throttled (slowed down) or suspended (paused). An older event may show warning.
statisticswindow_days; total_sent, hard_bounces and complaints as recipient counts; and bounce_rate and complaint_rate per recipient, as fractions.
urlOpens 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.

FilterMeaning
audience_idOnly this audience. Leave it out to cover every audience the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one.
Payload fieldMeaning
organization_idThe organization the audience belongs to.
audience_id, audience_nameThe audience. Pass the id to shipmail_get_audience.
subscriber_idPass it with audience_id to shipmail_get_subscriber.
email_addressThe subscriber's address. Untrusted when source is form.
sourceapi, dashboard or form.
created_atWhen they joined.
urlOpens the audience in Shipmail.

newsletter.sent

A newsletter finished sending. It fires once per newsletter. Needs permission to read newsletters.

FilterMeaning
audience_idOnly this audience. Leave it out to cover every audience the connection can read.
organization_idThe organization to watch. Needed when the connection covers more than one.
Payload fieldMeaning
organization_idThe organization.
newsletter_idPass it as id to shipmail_get_newsletter.
subjectWritten by your organization.
audience_idThe audience it went to, or null if it was deleted.
recipient_count, sent_count, failed_count, skipped_countHow many recipients it had, and how many emails were sent, failed or skipped.
sent_atWhen sending finished.
urlOpens 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.