> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifly.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger a campaign

> Trigger a campaign for the specified recipients.

> [!NOTE]
>
> The API can trigger campaigns for app push, web push, Kakao AlimTalk, Kakao Friendtalk, Kakao Brand Message, text messages, email, and LINE according to the project's channel configuration. Friendtalk is a legacy channel.

> [!WARNING]
>
> **Recipient types and personalization**
>
> An unsupported recipient type for the selected channel returns `400 Bad Request`.
>
> | Channel | Recipient types |
> | - | - |
> | App push, web push | `user-id` |
> | Kakao AlimTalk, Kakao Friendtalk, Kakao Brand Message, text message | `user-id`, `phone-number` |
> | Email | `user-id`, `email` |
> | LINE | `user-id`, `line-user-id` |
>
> Use `user-id` to look up user data for personalization. With other recipient types, Notifly uses the information in the request. For example, in `Hello {{ user["name"] }}`, the user name is empty and the recipient sees `Hello`.
>
> All recipient types support event parameters.

> [!NOTE]
>
> **How Notifly handles duplicates**
>
> Notifly sends once per unique device token for app push and web push. It sends once per unique phone number for Kakao AlimTalk, Kakao Friendtalk, Kakao Brand Message, and text messages. Email uses the email address, and LINE uses the LINE user ID.

> [!NOTE]
>
> **Invalid recipients in a 400 response**
>
> When recipient validation fails, the `400` response includes `errorDetails`.
>
> ```json
> {
>   "code": 400,
>   "success": false,
>   "error": "Bad request: invalid recipients",
>   "errorDetails": {
>     "reasonCode": "INVALID_RECIPIENTS",
>     "channel": "kakao-friendtalk",
>     "invalidRecipientCount": 2,
>     "invalidRecipients": [
>       {
>         "index": 0,
>         "type": "user-id",
>         "userId": "user_001",
>         "reasonCode": "MISSING_PHONE_NUMBER",
>         "source": { "pointer": "/recipients/0/userId" }
>       },
>       {
>         "index": 12,
>         "type": "user-id",
>         "userId": "user_013",
>         "reasonCode": "MISSING_PHONE_NUMBER",
>         "source": { "pointer": "/recipients/12/userId" }
>       }
>     ]
>   }
> }
> ```
>
> | Field | Type | Meaning |
> | - | - | - |
> | `reasonCode` | string | Always `INVALID_RECIPIENTS`. |
> | `channel` | string | Campaign channel. Values are `text-message`, `kakao-alimtalk`, `kakao-friendtalk`, `kakao-brand-message`, and `email`. |
> | `invalidRecipientCount` | number | Number of invalid recipients. |
> | `invalidRecipients` | array | List of invalid recipients. |
> | `invalidRecipients[].index` | number | Zero-based index in the request's `recipients` array. |
> | `invalidRecipients[].type` | string | Always `user-id`. |
> | `invalidRecipients[].userId` | string | `userId` supplied in the request. |
> | `invalidRecipients[].reasonCode` | string | `MISSING_PHONE_NUMBER` or `MISSING_EMAIL`. |
> | `invalidRecipients[].source.pointer` | string | Location of the request field as a JSON Pointer. |
>
> | Channel | Required field | `reasonCode` |
> | - | - | - |
> | `text-message` | `phone_number` | `MISSING_PHONE_NUMBER` |
> | `kakao-alimtalk` | `phone_number` | `MISSING_PHONE_NUMBER` |
> | `kakao-friendtalk` | `phone_number` | `MISSING_PHONE_NUMBER` |
> | `kakao-brand-message` | `phone_number` | `MISSING_PHONE_NUMBER` |
> | `email` | `email` | `MISSING_EMAIL` |
> | `push-notification`, `web-push-notification` | No contact field check | None |
>
> * A `400` response contains `code`, `success`, and `error`. Only recipient validation failures add `errorDetails`. Other `400` errors, such as invalid parameters or an inactive campaign, omit it.
> * A `user-id` recipient is invalid if the user exists in Notifly and lacks the required contact information. Notifly skips unknown user IDs.
> * When `partialSend` is `false` or omitted, one invalid recipient causes the entire request to fail with `400` and no messages are sent.
> * To retry, inspect `errorDetails.invalidRecipients` and remove the invalid recipients from the request.

> [!NOTE]
>
> **Partial sends**
>
> Set `partialSend` to `true` to send to valid recipients even if other recipients lack a phone number or email address.
>
> * With `partialSend: false` (the default), any invalid recipient causes the request to fail with `400` and sends no messages.
> * With `partialSend: true`, Notifly sends to valid recipients and lists the invalid recipients in the response. It returns `200` even when every recipient is invalid.
>
> Example response with `partialSend: true` and two invalid recipients.
>
> ```json
> {
>   "code": 200,
>   "success": true,
>   "error": null,
>   "errorDetails": {
>     "reasonCode": "INVALID_RECIPIENTS",
>     "channel": "kakao-alimtalk",
>     "invalidRecipientCount": 2,
>     "invalidRecipients": [
>       {
>         "index": 1,
>         "type": "user-id",
>         "userId": "user_002",
>         "reasonCode": "MISSING_PHONE_NUMBER",
>         "source": { "pointer": "/recipients/1/userId" }
>       },
>       {
>         "index": 3,
>         "type": "user-id",
>         "userId": "user_004",
>         "reasonCode": "MISSING_PHONE_NUMBER",
>         "source": { "pointer": "/recipients/3/userId" }
>       }
>     ]
>   }
> }
> ```
>
> Channels that support partial sends are `kakao-alimtalk`, `kakao-friendtalk`, `kakao-brand-message`, `text-message`, and `email`.
>
> > [!NOTE]
> >
> > This contact information check applies to recipients specified with `user-id`. It does not apply when you specify the recipient directly with `type: "phone-number"` or `type: "email"`.


## OpenAPI

````yaml /en/api-reference/openapi.yaml post /projects/{projectId}/campaigns/{campaignId}/send
openapi: 3.0.3
info:
  title: Notifly API
  version: 1.0.0
  contact:
    email: contact@notifly.tech
servers:
  - url: https://api.notifly.tech
    description: Notifly API server
security: []
tags:
  - name: catalog
    x-group: Catalogs
paths:
  /projects/{projectId}/campaigns/{campaignId}/send:
    post:
      summary: trigger-campaign
      operationId: triggerCampaign
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: Project ID.
        - name: campaignId
          in: path
          required: true
          schema:
            type: string
          description: Campaign ID from the console.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipients
              properties:
                recipients:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        description: >-
                          Recipient type. The default is `user-id`. Supported
                          types include `user-id`, `phone-number`, `email`, and
                          `line-user-id`.
                        enum:
                          - user-id
                          - phone-number
                          - email
                          - line-user-id
                      userId:
                        type: string
                        description: User ID. Required when `type` is `user-id`.
                      phoneNumber:
                        type: string
                        description: Phone number. Required when `type` is `phone-number`.
                      email:
                        type: string
                        description: Email address. Required when `type` is `email`.
                      lineUserId:
                        type: string
                        description: LINE user ID. Required when `type` is `line-user-id`.
                      eventParams:
                        type: object
                        description: Event parameters for message personalization.
                  description: List of recipients. Up to 1,000 entries.
                partialSend:
                  type: boolean
                  default: false
                  description: >-
                    When `true`, send to valid recipients even if some
                    recipients lack required phone numbers or email addresses.
                    The response lists any invalid recipients. When `false` or
                    omitted, an invalid recipient causes the entire request to
                    fail.
            examples:
              basicRequest:
                summary: Standard send request
                value:
                  recipients:
                    - type: phone-number
                      phoneNumber: 010-1234-5678
              partialSendRequest:
                summary: Partial send request
                value:
                  recipients:
                    - userId: user_001
                    - userId: user_002
                  partialSend: true
      responses:
        '200':
          description: >-
            The campaign was triggered. If `partialSend` is `true` and some
            recipients are invalid, the response includes `errorDetails`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  success:
                    type: boolean
                  error:
                    type: string
                    nullable: true
                  errorDetails:
                    type: object
                    description: >-
                      Included when `partialSend` is `true` and one or more
                      recipients are invalid.
                    properties:
                      reasonCode:
                        type: string
                        enum:
                          - INVALID_RECIPIENTS
                      channel:
                        type: string
                        description: Campaign channel.
                      invalidRecipientCount:
                        type: integer
                        description: Number of invalid recipients.
                      invalidRecipients:
                        type: array
                        description: Details about invalid recipients.
                        items:
                          type: object
                          properties:
                            index:
                              type: integer
                            type:
                              type: string
                            userId:
                              type: string
                            reasonCode:
                              type: string
                              enum:
                                - MISSING_PHONE_NUMBER
                                - MISSING_EMAIL
                            source:
                              type: object
                              properties:
                                pointer:
                                  type: string
              examples:
                successNoInvalid:
                  summary: All recipients valid (no errorDetails)
                  value:
                    code: 200
                    success: true
                    error: null
                partialSendWithInvalid:
                  summary: Partial send with invalid recipients
                  value:
                    code: 200
                    success: true
                    error: null
                    errorDetails:
                      reasonCode: INVALID_RECIPIENTS
                      channel: kakao-alimtalk
                      invalidRecipientCount: 2
                      invalidRecipients:
                        - index: 1
                          type: user-id
                          userId: user_002
                          reasonCode: MISSING_PHONE_NUMBER
                          source:
                            pointer: /recipients/1/userId
                        - index: 3
                          type: user-id
                          userId: user_004
                          reasonCode: MISSING_PHONE_NUMBER
                          source:
                            pointer: /recipients/3/userId
        '400':
          description: >-
            The request is incorrect. `errorDetails` is included only when
            recipient validation fails.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  success:
                    type: boolean
                  error:
                    type: string
                  errorDetails:
                    type: object
                    description: >-
                      Included only when recipient validation fails, such as
                      when a `user-id` recipient lacks required contact
                      information.
                    required:
                      - reasonCode
                      - channel
                      - invalidRecipientCount
                      - invalidRecipients
                    properties:
                      reasonCode:
                        type: string
                        enum:
                          - INVALID_RECIPIENTS
                        description: Code that identifies a recipient validation failure.
                      channel:
                        type: string
                        description: Campaign channel.
                      invalidRecipientCount:
                        type: integer
                        description: Number of invalid recipients.
                      invalidRecipients:
                        type: array
                        description: Details about invalid recipients.
                        items:
                          type: object
                          required:
                            - index
                            - type
                            - userId
                            - reasonCode
                            - source
                          properties:
                            index:
                              type: integer
                              description: >-
                                Zero-based index in the request's `recipients`
                                array.
                            type:
                              type: string
                              enum:
                                - user-id
                              description: Recipient type.
                            userId:
                              type: string
                              description: The `userId` supplied in the request.
                            reasonCode:
                              type: string
                              enum:
                                - MISSING_PHONE_NUMBER
                                - MISSING_EMAIL
                              description: >-
                                Type of required contact information that is
                                missing.
                            source:
                              type: object
                              required:
                                - pointer
                              properties:
                                pointer:
                                  type: string
                                  description: >-
                                    Location of the request field as a JSON
                                    Pointer.
              examples:
                generalBadRequest:
                  summary: General 400 response (without errorDetails)
                  value:
                    code: 400
                    success: false
                    error: 'Bad request: some-error-message'
                invalidRecipients:
                  summary: Recipient validation failure (with errorDetails)
                  value:
                    code: 400
                    success: false
                    error: 'Bad request: invalid recipients'
                    errorDetails:
                      reasonCode: INVALID_RECIPIENTS
                      channel: kakao-friendtalk
                      invalidRecipientCount: 2
                      invalidRecipients:
                        - index: 0
                          type: user-id
                          userId: user_001
                          reasonCode: MISSING_PHONE_NUMBER
                          source:
                            pointer: /recipients/0/userId
                        - index: 12
                          type: user-id
                          userId: user_013
                          reasonCode: MISSING_PHONE_NUMBER
                          source:
                            pointer: /recipients/12/userId
        '401':
          description: The token has expired, or the authentication information is invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  success:
                    type: boolean
                  error:
                    type: string
              example:
                code: 401
                success: false
                error: 'Unauthorized: Invalid token'
        '405':
          description: Unsupported HTTP Method.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  success:
                    type: boolean
                  error:
                    type: string
              example:
                code: 405
                success: false
                error: 'Method not allowed: some-error-message'
        '413':
          description: The request payload is too large.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  success:
                    type: boolean
                  error:
                    type: string
              example:
                code: 413
                success: false
                error: 'Payload too large: some-error-message'
        '500':
          description: >-
            Notifly server error. If 500 errors persist, please contact the
            Notifly team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  success:
                    type: boolean
                  error:
                    type: string
              example:
                code: 500
                success: false
                error: some-error-message
        '501':
          description: The feature is not yet supported.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  success:
                    type: boolean
                  error:
                    type: string
              example:
                code: 501
                success: false
                error: 'Not implemented: some-error-message'
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Pass the token issued by `POST /authenticate` as a bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.