# Transactional API Examples

This page contains some example requests to help get you started with our transactional API.

### Send an email using a transactional message template[](#send-an-email-using-a-transactional-message-template)

To send a message using a transactional message template, you need the following:

*   `transactional_message_id`: This is found in the code examples when setting up a transactional message. It’s also the id listed in the URL of a transactional message.
    
    [![image.png](https://docs.customer.io/images/image%28556%29.png)](#61a6a12dc54bedaef7b4f8ea9883d06a-lightbox)
    
*   `message_data`: A list of data that you want to pass into your message using [liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable `{{customer.first_name}}`.](/using-liquid).
*   Your API Key: This is how you’ll authenticate with Customer.io’s API. You can find or create your App API key from your [Account Settings](https://fly.customer.io/settings/api_credentials?keyType=app).
*   Recipient email - The email address for the `to` field, and
*   `identifiers.id`, `identifiers.email`, or `identifiers.cio_id`: a unique identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for the recipient, so your message is associated with the correct person.

Using the data above, you can trigger a message with a request like the one below. This example is for a transactional message that includes two variables: `first_name` and `passwordResetURL`.

```fallback
message='
{
  "to": "Sarah <sarah@example.io>",
  "transactional_message_id": 3,
  "message_data": {
    "first_name": "Sarah",
    "passwordResetURL": "https://www.example.io/password?token=12345"
  },
  "identifiers": {
    "id":"sf3sd"
  }
}
'

echo $message | curl -v https://api.customer.io/v1/send/email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d @-
```

### Send an email without a transactional template[](#send-an-email-without-a-transactional-template)

To send a simple request that doesn’t use a transactional template, you must provide all of your message information—`to`, `from`, `subject`, `body`, and one of `identifiers.id`, `identifiers.email`, or `identifiers.cio_id`—in the request.

```fallback
message='
{
  "to": "Sarah <sarah@example.io>",
  "from":"win@customer.io",
  "subject":"Reset your password",
  "body":"Hello Sarah, you or someone in your team account has requested a password reset on your behalf.  Reset your password by clicking <a href='https://www.example.io/password?token=12345'>here</a>.</p>", 
  "identifiers": {
    "id":"d34sh"
  }
}
'

echo $message | curl -v https://api.customer.io/v1/send/email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d @-
```

 Messages sent without a `transactional_message_id` are ‘uncategorized’

Any messages you send without a `transactional_message_id` are grouped together in the **All Uncategorized Messages** bucket in your workspace. We strongly recommend creating transactional message templates, so that it’s easier to manage your messages and to separate reporting metrics for your different types of transactional messages.

### Including an attachment[](#including-an-attachment)

 Include PDF attachments from the asset library

While you can encode attachment and send them directly to people, you can also host PDFs in our [asset library](/journeys/asset-library) and link to them in your messages. This can save you the trouble of encoding and sending files directly.

You can include base64-encoded attachments in your request, like calendar invites, in the format: `{"filename": "base64-encoded-file-body"}`. Total attachments size, across all attachments for the message, must be under 2MB.

For example, here’s the text body of a simple calendar invite (example\_invite.ics):

```fallback
BEGIN:VCALENDAR
VERSION:2.0
PRODID:http://www.icalmaker.com
BEGIN:VEVENT
UID:http://www.icalmaker.com/event/69f018d0-a2b1-44c0-ac66-a28e8c493a6b
DTSTAMP:20201113T220919Z
DTSTART:20230504T113000Z
DTEND:20230504T123000Z
SUMMARY:Customer.io Calendar Example
LOCATION:921 SW Washington St., Suite 820, Portland, OR 97205
DESCRIPTION:Learn more about sending calendar invites as attachments at https://customer.io/transactional-api. 
END:VEVENT
END:VCALENDAR
```

You can base64-encode the invite and include it in your request like this.

```fallback
message='
{
  "to": "Sandra <sandra@example.io>",
  "from":"win@customer.io",
  "subject":"Registration Confirmation",
  "body":"Attached is an invite to add to your calendar.", 
  "identifiers": {"id":"e5zs8"},
  "attachments":{"example_invite.ics": "QkVHSU46VkNBTEVOREFSClZFUlNJT046Mi4wClBST0RJRDpodHRwOi8vd3d3LmljYWxtYWtlci5jb20KQkVHSU46VkVWRU5UClVJRDpodHRwOi8vd3d3LmljYWxtYWtlci5jb20vZXZlbnQvNjlmMDE4ZDAtYTJiMS00NGMwLWFjNjYtYTI4ZThjNDkzYTZiCkRUU1RBTVA6MjAyMDExMTNUMjIwOTE5WgpEVFNUQVJUOjIwMjMwNTA0VDExMzAwMFoKRFRFTkQ6MjAyMzA1MDRUMTIzMDAwWgpTVU1NQVJZOkN1c3RvbWVyLmlvIENhbGVuZGFyIEV4YW1wbGUKTE9DQVRJT046OTIxIFNXIFdhc2hpbmd0b24gU3QuLCBTdWl0ZSA4MjAsIFBvcnRsYW5kLCBPUiA5NzIwNQpERVNDUklQVElPTjpMZWFybiBtb3JlIGFib3V0IHNlbmRpbmcgY2FsZW5kYXIgaW52aXRlcyBhcyBhdHRhY2htZW50cyBhdCBodHRwczovL2N1c3RvbWVyLmlvL3RyYW5zYWN0aW9uYWwtYXBpLiAKRU5EOlZFVkVOVApFTkQ6VkNBTEVOREFS"}
}
'
echo $message | curl -v https://api.customer.io/v1/send/email \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d @-
```

The request results in a delivery with a calendar invite, which looks like this in Gmail:

[![image.png](https://docs.customer.io/images/image%28560%29.png)](#68347cc13beb7743979afd9fac390e40-lightbox)

### Send a push notification using a transactional message template[](#send-a-push-notification-using-a-transactional-message-template)

To send a transactional push notification, you need the following:

*   `transactional_message_id`: This is found in the code examples when setting up a transactional message. It’s also the id listed in the URL of a transactional message.
    
    [![image.png](https://docs.customer.io/images/image%28556%29.png)](#61a6a12dc54bedaef7b4f8ea9883d06a-lightbox)
    
*   `message_data`: A list of data that you want to pass into your message using [liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable `{{customer.first_name}}`.](/using-liquid).
*   Your API Key: This is how you’ll authenticate with Customer.io’s API. You can find or create your App API key from your [Account Settings](https://fly.customer.io/settings/api_credentials?keyType=app).
*   `identifiers.id`, `identifiers.email`, or `identifiers.cio_id`: a unique identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for the recipient, so your message is associated with the correct person.

Using the data above, you can trigger a message with a request like the one below. This example is for a transactional message that sends a push notification to the recipient’s last used device and includes two variables: `first_name` and `passwordResetToken`.

```fallback
message='
{
  "to": "last_used",
  "transactional_message_id": 3,
  "message_data": {
    "first_name": "Sarah",
    "passwordResetToken": "token=12345"
  },
  "identifiers": {
    "id":"sf3sd"
  }
}
'

echo $message | curl -v https://api.customer.io/v1/send/push \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP-API-TOKEN' \
-d @-
```

### Need help?[](#need-help)

If you have another use case in mind, or need help applying one of these examples, [let us know](mailto://win@customer.io)!