# Newsletter API

Send newsletters built in Make, trigger recurring actions, and fetch delivery and engagement statistics for each sending.

- Base URL: `https://newsletters.dialogapi.no`
- OpenAPI spec: https://apidocs.make.as/api-docs/public/newsletters

## Newsletters

### Creates sending

`POST /api/public/v1/newsletters/{id}/send`

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | newsletter ID |
| `segment_id` | body | integer |  |  |
| `list_ids` | body | integer[] |  |  |
| `sender_id` | body | integer |  |  |
| `scheduled_at` | body | string |  |  |

Responses:

- `200` Return stats
- `401` Unathorized
- `422` Return error

Request:

```bash
curl --request POST \
  --user 'user_id:api_key' \
  --header 'content-type: application/json' \
  --data '{ "segment_id": 1, "list_ids": [ 1 ], "sender_id": 1, "scheduled_at": "2026-01-01T12:00:00Z" }' \
  --url 'https://newsletters.dialogapi.no/api/public/v1/newsletters/{id}/send'
```

Example response (200):

```json
{
  "id": 32,
  "clicks": 0,
  "unique_clicks": 0,
  "opens": 0,
  "bounce": 0,
  "unsubscribes": 0,
  "tracking_mode": "count",
  "sent": 0,
  "created_at": "2026-01-01T12:00:00.000+01:00",
  "sent_at": null,
  "openrate": 0,
  "newsletter_screenshot_url": "http://localhost:3000/v4/d013455e-f392-46d5-851e-08f5fe4735c7/1767265200",
  "mailbody": "https://example.com/v/d013455e-f392-46d5-851e-08f5fe4735c7",
  "delivered": 0,
  "subject": "Subject",
  "from_email": "personal@email.com",
  "tags": [],
  "sending_id": null,
  "segment": {
    "id": "1",
    "title": null
  }
}
```

### Show newsletters stats

`GET /api/public/v1/newsletters/stats`

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from_date` | query | string |  |  |
| `to_date` | query | string |  |  |

Responses:

- `200` Return stats
- `400` Return error
- `401` Unathorized

Request:

```bash
curl --request GET \
  --user 'user_id:api_key' \
  --header 'content-type: application/json' \
  --url 'https://newsletters.dialogapi.no/api/public/v1/newsletters/stats'
```

Example response (200):

```json
[
  {
    "id": 37,
    "clicks": 30,
    "unique_clicks": 10,
    "opens": 90,
    "bounce": 5,
    "unsubscribes": 3,
    "tracking_mode": "standard",
    "sent": 100,
    "created_at": "2020-11-20T12:30:00.000+01:00",
    "sent_at": "2020-11-20T12:30:00.000+01:00",
    "openrate": 94.7,
    "newsletter_screenshot_url": "http://localhost:3000/v4/8ccdcc45-3a39-4962-8142-487ae67daeca/1767265200",
    "mailbody": "https://example.com/v/8ccdcc45-3a39-4962-8142-487ae67daeca",
    "delivered": 95,
    "subject": "SendingSubject",
    "from_email": "testmail@mail.sndr.nb",
    "tags": [],
    "sending_id": 0,
    "lists": [
      {
        "id": "1",
        "title": "ListTitle1"
      },
      {
        "id": "2",
        "title": "ListTitle2"
      }
    ]
  }
]
```

### Show newsletter stats

`GET /api/public/v1/newsletters/{id}/stats`

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | sending ID |

Responses:

- `200` Return stats
- `401` Unathorized
- `404` Not Found

Request:

```bash
curl --request GET \
  --user 'user_id:api_key' \
  --header 'content-type: application/json' \
  --url 'https://newsletters.dialogapi.no/api/public/v1/newsletters/{id}/stats'
```

Example response (200):

```json
{
  "id": 43,
  "clicks": 30,
  "unique_clicks": 10,
  "opens": 90,
  "bounce": 5,
  "unsubscribes": 3,
  "tracking_mode": "standard",
  "sent": 100,
  "created_at": "2020-11-20T12:30:00.000+01:00",
  "sent_at": "2020-11-20T12:30:00.000+01:00",
  "openrate": 94.7,
  "newsletter_screenshot_url": "http://localhost:3000/v4/8ccdcc45-3a39-4962-8142-487ae67daeca/1767265200",
  "mailbody": "https://example.com/v/8ccdcc45-3a39-4962-8142-487ae67daeca",
  "delivered": 95,
  "subject": "SendingSubject",
  "from_email": "testmail@mail.sndr.nb",
  "tags": [
    "tagtitle"
  ],
  "sending_id": 0,
  "lists": [
    {
      "id": "1",
      "title": "ListTitle1"
    },
    {
      "id": "2",
      "title": "ListTitle2"
    }
  ]
}
```

### Show newsletter stats

`GET /api/public/v1/newsletters/{id}/stats_by_external_guid`

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | sending external ID |

Responses:

- `200` Return stats
- `401` Unathorized
- `404` Not Found

Request:

```bash
curl --request GET \
  --user 'user_id:api_key' \
  --header 'content-type: application/json' \
  --url 'https://newsletters.dialogapi.no/api/public/v1/newsletters/{id}/stats_by_external_guid'
```

Example response (200):

```json
{
  "id": 47,
  "clicks": 30,
  "unique_clicks": 10,
  "opens": 90,
  "bounce": 5,
  "unsubscribes": 3,
  "tracking_mode": "standard",
  "sent": 100,
  "created_at": "2020-11-20T12:30:00.000+01:00",
  "sent_at": "2020-11-20T12:30:00.000+01:00",
  "openrate": 94.7,
  "newsletter_screenshot_url": "http://localhost:3000/v4/8ccdcc45-3a39-4962-8142-487ae67daeca/1767265200",
  "mailbody": "https://example.com/v/8ccdcc45-3a39-4962-8142-487ae67daeca",
  "delivered": 95,
  "subject": "SendingSubject",
  "from_email": "testmail@mail.sndr.nb",
  "tags": [
    "tagtitle"
  ],
  "sending_id": 0,
  "lists": [
    {
      "id": "1",
      "title": "ListTitle1"
    },
    {
      "id": "2",
      "title": "ListTitle2"
    }
  ]
}
```

## Recurring actions

### Return list of existing recurring actions

`GET /api/public/v1/recurring_actions`

Responses:

- `200` Return recurring actions
- `401` Unathorized

Request:

```bash
curl --request GET \
  --user 'user_id:api_key' \
  --header 'content-type: application/json' \
  --url 'https://newsletters.dialogapi.no/api/public/v1/recurring_actions'
```

Example response (200):

```json
[
  {
    "id": 1,
    "name": "Action #1",
    "action": "send_email"
  }
]
```

### Trigger recurring action by ID

`POST /api/public/v1/recurring_actions/{id}/trigger`

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | ID of recurring action |
| `guids` | body | string[] |  |  |

Responses:

- `200` Recurring action started
- `401` Unathorized
- `404` Not Found

Request:

```bash
curl --request POST \
  --user 'user_id:api_key' \
  --header 'content-type: application/json' \
  --data '{ "guids": [ "guids" ] }' \
  --url 'https://newsletters.dialogapi.no/api/public/v1/recurring_actions/{id}/trigger'
```