Skip to main content

Trigger Event

Required fields​

email

The email of the contact that triggered the event - If a contact with the email does not already exist it will be created

identifier

The identifier of the event to trigger.

Events can be created under the Events tab of the dashboard.

Optional fields​

consentsToEmails

Default value: true

If the created contact consents to receive emails or not

contactMetadata

Default value: empty object

Metadata that should be added to the contact when the event is triggered. If the field already exists on the contact it will be updated with the new values.

{
  "contactMetadata": {
    "First Name": "John"
    "Last Name": "Doe",
    "Country": "UK",
    "Last signed in": "2024-03-11T13:50:00.000Z"
  }
}

triggerMetadata

Default value: empty object

Metadata that should only be used for the duration of the request and in subsequent Automations triggered by the event.

The forgot_password_link field in the request will be substituted with the {{forgot_password_link}} template variable in the Email Template

{
  "triggerMetadata": {
    "forgot_password_link": "https://app-url.com/forgot-password/unique-password-reset-page"
  }
}

Example:

If the metadata field already exists on the contact it will be updated

curl -X POST https://api.cocomail.io/events/trigger \
    -H "Authorization: <API_TOKEN>" \
    -d '{
        "email":"user@example.com",
        "identifier":"FORGOT_PASSWORD",
        "consentsToEmails":"true",
        "contactMetadata": {
          "forgot_password_at": "2024-03-11T13:45:00.000Z"
        },
        "triggerMetadata": {
          "forgot_password_link": "https://app-url.com/forgot-password/unique-password-reset-page"
        }
      }'

Example Response​

{
  "data":{
    "contact":{
        "id":"018e32c3-4fd6-71cb-9425-ebd7f8ac09d2",
        "email":"user@example.com",
        "metadata":{
          "forgot_password_at":"2024-03-18T10:25:00.000Z"
        },
        "createdAt":"2024-03-12T13:04:04.566Z"
    },
    "event":{
        "id":"018e50e3-5b19-734e-ab70-4909b83426ec",
        "name":"Forgot Password",
        "identifier":"FORGOT_PASSWORD",
        "createdAt":"2024-03-18T09:27:41.000Z"
    },
    "trigger":{
        "metadata":{
          "forgot_password_link":"https://app-url.com/forgot-password/unique-password-reset-page"
        }
    }
  },
  "error":null
}

Example Error Response​

{
  "data": null,
  "error": "Event with identifier INVALID_EVENT_IDENTIFIER not found"
}