---
title: "Create Message"
method: POST
path: "/api/v1/app/{app_id}/msg"
tags: ["Message"]
---

# Create Message

`POST /api/v1/app/{app_id}/msg`

Creates a new message and dispatches it to all of the application's endpoints.

The `eventId` is an optional custom unique ID. It's verified to be unique only up to a day, after that no verification will be made.
If a message with the same `eventId` already exists for the application, a 409 conflict error will be returned.

The `eventType` indicates the type and schema of the event. All messages of a certain `eventType` are expected to have the same schema. Endpoints can choose to only listen to specific event types.
Messages can also have `channels`, which similar to event types let endpoints filter by them. Unlike event types, messages can have multiple channels, and channels don't imply a specific message content or schema.

The `payload` property is the webhook's body (the actual webhook message). Svix supports payload sizes of up to 1MiB, though it's generally a good idea to keep webhook payloads small, probably no larger than 40kb.

## Path parameters

- `app_id` string, required — The Application's ID or UID.

## Query parameters

- `with_content` boolean — When `true`, message payloads are included in the response.

## Headers

- `idempotency-key` string

## Request body

- MessageIn
  - `eventId` string, nullable — Optional unique identifier for the message
  - `eventType` string, required — The event type's name
  - `payload` object, required — JSON payload to send as the request body of the webhook. We also support sending non-JSON payloads. Please contact us for more information.
  - `channels` string[], nullable — List of free-form identifiers that endpoints can filter by
  - `application` ApplicationIn
    - `name` string, required — Application name for human consumption.
    - `rateLimit` integer, nullable — Deprecated, use `throttleRate` instead.
    - `throttleRate` integer, nullable — Maximum messages per second to send to this application. Outgoing messages will be throttled to this rate.
    - `uid` string, nullable — Optional unique identifier for the application.
    - `metadata` object
  - `tags` string[], nullable — List of free-form tags that can be filtered by when listing messages
  - `transformationsParams` object, nullable — Extra parameters to pass to Transformations (for future use)
  - `deliverAt` string, date-time, nullable — The date and time at which the message will be delivered. Note that this time is best-effort-only. Must be at least one minute and no more than 24 hours in the future.
  - `payloadRetentionPeriod` integer, nullable — Optional number of days to retain the message payload. Defaults to 90. Note that this is mutually exclusive with `payloadRetentionHours`.
  - `payloadRetentionHours` integer, nullable — Optional number of hours to retain the message payload. Note that this is mutually exclusive with `payloadRetentionPeriod`.

## Response `202`

- MessageOut
  - `eventId` string, nullable — Optional unique identifier for the message
  - `eventType` string, required — The event type's name
  - `payload` object, required
  - `channels` string[], nullable — List of free-form identifiers that endpoints can filter by
  - `id` string, required — The Message's ID.
  - `timestamp` string, date-time, required
  - `tags` string[], nullable
  - `deliverAt` string, date-time, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `413` — Payload too large
- `422` — Validation Error
- `429` — Too Many Requests

---

[API](https://skmtc.net/svix/apis/svix-api.md) · [All operations](https://skmtc.net/svix/apis/svix-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/svix/svix-api/versions/16dbcc056c48/schema)