---
url: https://next.zammad.org/en/reference/rest-api/articles.md
---

# Article

## General

Some attributes of articles might not be straight forward or come with
fairly many options - below list hopefully helps you on this journey.

### `content_type`

Zammad supports `text/html` for HTML formatted text or `text/plain` for
plain text. This allows you to have better formatting options if you
need them.

Zammad web UI usually uses `text/html`.

### `type`

Zammad supports a huge number of article types. Below list may be
incomplete depending on your instance and possibly installed add-ons /
custom changes.

If not stated otherwise, all article types below are **communication
articles** and thus affecting SLA calculation in Zammad defaults.

The difference is that communication articles provide the option to
reply automatically. Which actions exactly are available depends on the
article type and e.g. recipient lists.

`email`
: This allows you to create incoming or outgoing email articles.
However, this highly depends on the chosen `sender`.

`phone`
:
Indicates phone notes.

`web`
: Usually used by customers only. This type is being used when ever your
customer uses the web UI to create articles.

`note`
: When ever a communication does not fit (e.g.: internal notes) choose
note. Zammad also uses this article type as default fall back.

This is **not a communication article**.

`sms`
:
This type is being used for Zammad's SMS integration.

`chat`
: This article type is technically a place holder and is only available
via API.

`fax`
: This article type is technically a place holder and is only available
via API.

`twitter status` & `twitter direct-message`
: These articles types are used by Zammad's twitter channel. Technically
you can use these to automatically respond to existing requests via
twitter.

`facebook feed post` & `facebook feed comment`
: These articles types are used by Zammad's Facebook channel. Technically
you can use these to automatically respond to existing requests via
Facebook.

`telegram personal-message`
: Used by Zammad's Telegram channel. Technically you can use these to
automatically respond to existing requests via Telegram.

### `internal`

This attribute allows you to set the visibility of your articles. For
internal visible only use `true`, for visibly for your customers as well
use `false`.

::: warning
**Visibility: internal doesn't mean it's silent**

If you set an article to `internal: true` but choose to send an email,
please be aware that said email is still being sent out!
:::

### `sender`

Indicates which use did create the article. You can choose from:

* `Agent`
* `Customer`
* `System`

::: warning
Depending of above selection, some article types may not be available
or behave different. Please be aware that `System` causes users not
being able to read the bodies (this works similar to Zammads trigger
displaying in tickets).
:::

## List articles by ticket

Required permission: `ticket.agent` **or** `ticket.customer`

`GET`-Request sent: `/api/v1/ticket_articles/by_ticket/{ticket id}`

::: details

```json
// HTTP-Code 200 OK

[
  {
    "id": 9,
    "ticket_id": 5,
    "type_id": 1,
    "sender_id": 2,
    "from": "David Bell <david@example.com>",
    "to": "support@fastlane.inc",
    "cc": null,
    "subject": null,
    "reply_to": null,
    "message_id": null,
    "message_id_md5": null,
    "in_reply_to": null,
    "content_type": "text/html",
    "references": null,
    "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magnam aliquam quaerat voluptatem.<br>\nDavid Bell<br>\n<span class=\"js-signatureMarker\"></span>\n<br>\nDavid Bell",
    "internal": false,
    "preferences": {},
    "updated_by_id": 10,
    "created_by_id": 10,
    "origin_by_id": null,
    "created_at": "2021-08-02T11:57:18.068Z",
    "updated_at": "2021-08-02T11:57:18.068Z",
    "attachments": [],
    "inline_attachments": [],
    "type": "email",
    "sender": "Customer",
    "created_by": "david@example.com",
    "updated_by": "david@example.com",
    "time_unit": null
  },
  {
    "id": 10,
    "ticket_id": 5,
    "type_id": 1,
    "sender_id": 1,
    "from": "Emily Wilson via <support@fastlane.inc>",
    "to": "David Bell <david@example.com>",
    "cc": null,
    "subject": null,
    "reply_to": null,
    "message_id": null,
    "message_id_md5": null,
    "in_reply_to": null,
    "content_type": "text/html",
    "references": null,
    "body": "Hi David,<br>\n<br>\nUt enim aeque doleamus animo, cum corpore dolemus, fieri tamen permagna accessio potest, si aliquod aeternum et infinitum impendere malum nobis opinemur.<br>\n<span class=\"js-signatureMarker\"></span>\n<br>\n--<br>\nGreetings,<br>\n<br>\nEmily Wilson<br>",
    "internal": false,
    "preferences": {},
    "updated_by_id": 5,
    "created_by_id": 5,
    "origin_by_id": null,
    "created_at": "2021-08-03T09:57:18.121Z",
    "updated_at": "2021-08-03T09:57:18.121Z",
    "attachments": [],
    "inline_attachments": [],
    "type": "email",
    "sender": "Agent",
    "created_by": "emily@fastlane.inc",
    "updated_by": "emily@fastlane.inc"
  }
]

```

:::

## List specific article

Required permission: `ticket.agent` **or** `ticket.customer`

`GET`-Request sent: `/api/v1/ticket_articles/{article id}`

::: details

```json
// HTTP-Code 200 OK

{
  "id": 9,
  "ticket_id": 5,
  "type_id": 1,
  "sender_id": 2,
  "from": "David Bell <david@example.com>",
  "to": "support@fastlane.inc",
  "cc": null,
  "subject": null,
  "reply_to": null,
  "message_id": null,
  "message_id_md5": null,
  "in_reply_to": null,
  "content_type": "text/html",
  "references": null,
  "body": "Hi,<br>\n<br>\n<u>Qui liber cum et mortem contemnit, qua qui est imbutus quietus esse numquam potest. Praeterea bona praeterita grata recordatione renovata delectant.<br>\n<span class=\"js-signatureMarker\"></span>\n<br>\nDavid Bell",
  "internal": false,
  "preferences": {},
  "updated_by_id": 10,
  "created_by_id": 10,
  "origin_by_id": null,
  "created_at": "2021-08-02T11:57:18.068Z",
  "updated_at": "2021-08-02T11:57:18.068Z",
  "attachments": [],
  "inline_attachments": [],
  "type": "email",
  "sender": "Customer",
  "created_by": "david@example.com",
  "updated_by": "david@example.com",
  "time_unit": null
}

```

:::

## Create

Required permission: `ticket.agent` **or** `ticket.customer`

`POST`-Request sent: `/api/v1/ticket_articles`

::: tip
If you want to create articles on behalf of other users (e.g. for a
phone note), use the `origin_by_id` attribute. `ticket.agent`
permission is mandatory for this.
:::

### Plain article

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "ticket_id": 5,
  "subject": "Call note",
  "body": "Called the customer and discussed their issues.<br/>Turns out these were caused by invalid configurations - solved.",
  "content_type": "text/html",
  "type": "phone",
  "internal": false,
  "sender": "Agent",
  "time_unit": "15"
}

```

\=== Response

```json
// HTTP-Code 201 Created

{
  "id": 33,
  "ticket_id": 5,
  "type_id": 5,
  "sender_id": 1,
  "from": "Lauren Brooks",
  "to": null,
  "cc": null,
  "subject": "Call note",
  "reply_to": null,
  "message_id": null,
  "message_id_md5": null,
  "in_reply_to": null,
  "content_type": "text/html",
  "references": null,
  "body": "Called the customer and discussed their issues.<br>Turns out these were caused by invalid configurations - solved.",
  "internal": false,
  "preferences": {},
  "updated_by_id": 3,
  "created_by_id": 3,
  "origin_by_id": null,
  "created_at": "2021-11-08T16:13:35.962Z",
  "updated_at": "2021-11-08T16:13:35.962Z",
  "attachments": [],
  "inline_attachments": [],
  "type": "phone",
  "sender": "Agent",
  "created_by": "lauren@fastlane.inc",
  "updated_by": "lauren@fastlane.inc"
}

```

:::
::::

### Article with attached files

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "ticket_id": 5,
  "to": "",
  "cc": "",
  "subject": "some subject",
  "body": "Please see attached file...",
  "content_type": "text/plain",
  "type": "note",
  "internal": true,
  "time_unit": "25",
  "attachments": [
    {
      "filename": "portal.txt",
      "data": "VGhlIGNha2UgaXMgYSBsaWUhCg==",
      "mime-type": "text/plain"
    },
    {
      "filename": "{filename}",
      "data": "{file content base64 encoded}",
      "mime-type": "{attachments mime-type}"
    }
  ]
}

```

\=== Response

```json
// HTTP-Code 201 Created

{
  "id": 35,
  "ticket_id": 5,
  "type_id": 10,
  "sender_id": 1,
  "from": "Lauren Brooks",
  "to": "",
  "cc": "",
  "subject": "some subject",
  "reply_to": null,
  "message_id": null,
  "message_id_md5": null,
  "in_reply_to": null,
  "content_type": "text/plain",
  "references": null,
  "body": "Please see attached file...",
  "internal": true,
  "preferences": {},
  "updated_by_id": 3,
  "created_by_id": 3,
  "origin_by_id": null,
  "created_at": "2021-11-09T12:02:55.434Z",
  "updated_at": "2021-11-09T12:02:55.434Z",
  "attachments": [
    {
      "id": 17,
      "filename": "portal.txt",
      "size": "19",
      "preferences": {
        "Mime-Type": "text/plain"
      }
    }
  ],
  "inline_attachments": [],
  "type": "note",
  "sender": "Agent",
  "created_by": "lauren@fastlane.inc",
  "updated_by": "lauren@fastlane.inc"
}

```

:::
::::

### Article with inline images

Inline images can be used by providing data URIs in your HTML markup.
In the response, they are listed under `inline_attachments`, while
`attachments` only contains regular file attachments.

:::: details

::: tabs key:reqres

\=== Request

```json
{
  "ticket_id": 5,
  "to": "",
  "cc": "",
  "subject": "some subject",
  "body": "Let's see the <b>phoenix</b> <img src=\"data:image/png;base64,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\">",
  "content_type": "text/html",
  "type": "note",
  "internal": false,
  "time_unit": "12"
}

```

\=== Response

```json
// HTTP Code 201 Created

{
  "id": 37,
  "ticket_id": 5,
  "type_id": 10,
  "sender_id": 1,
  "from": "Lauren Brooks",
  "to": "",
  "cc": "",
  "subject": "some subject",
  "reply_to": null,
  "message_id": null,
  "message_id_md5": null,
  "in_reply_to": null,
  "content_type": "text/html",
  "references": null,
  "body": "Let's see the <b>phoenix</b> <img src=\"/api/v1/ticket_attachment/5/37/19?view=inline\" style=\"max-width:100%;\">",
  "internal": false,
  "preferences": {},
  "updated_by_id": 3,
  "created_by_id": 3,
  "origin_by_id": null,
  "created_at": "2021-11-09T12:10:49.375Z",
  "updated_at": "2021-11-09T12:10:49.375Z",
  "attachments": [],
  "inline_attachments": [
    {
      "id": 19,
      "filename": "image1.png",
      "size": "3735",
      "preferences": {
        "Content-Type": "image/png",
        "Mime-Type": "image/png",
        "Content-ID": "5.e384b84e-bfef-49f7-af22-8546fb99f8dc@fqdn",
        "Content-Disposition": "inline"
      }
    }
  ],
  "type": "note",
  "sender": "Agent",
  "created_by": "lauren@fastlane.inc",
  "updated_by": "lauren@fastlane.inc"
}

```

:::
::::

## Receive attachments

Now that you have all those fancy attachments within your tickets, you
may want to download specific ones.

`GET`-Request sent:
`/api/v1/ticket_attachment/{ticket id}/{article id}/{attachment id}`

Response: `{image file}`

::: tip
If you're not sure which articles a ticket contains, please
[list](#list-articles-by-ticket) affected articles first.
:::