Skip to content
MailBench SMTP
Start free
Menu
Documentation menu

API reference

Tags

Label messages by hand or with rules.

Add a tag to a message

POST/v1/messages/{id}/tags

Path parameters

  • idstringrequired
    Message ID.

Request body

  • tagstringrequired

Returns

  • tagstringrequired

Errors

400The request was malformed or a value was invalid.
401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X POST "https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag": "billing"}'
const res = await fetch("https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "tag": "billing"
  }),
});
const { data } = await res.json();
import os, requests

res = requests.post(
    "https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "tag": "billing",
    },
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "tag": "string"
  }
}

Replace a message's tags

PUT/v1/messages/{id}/tags

Path parameters

  • idstringrequired
    Message ID.

Request body

  • tagsarray of stringsrequired

Returns

  • tagsarray of stringsrequired

Errors

400The request was malformed or a value was invalid.
401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X PUT "https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": [ "billing" ]}'
const res = await fetch("https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "tags": [
      "billing"
    ]
  }),
});
const { data } = await res.json();
import os, requests

res = requests.put(
    "https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "tags": [
            "billing",
        ],
    },
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "tags": [
      "billing"
    ]
  }
}

Remove a tag from a message

DELETE/v1/messages/{id}/tags/{name}

Path parameters

  • idstringrequired
    Message ID.
  • namestringrequired
    The tag to remove. URL-encode it.

Returns

  • removedstringrequired

Errors

401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X DELETE "https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags/<name>" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags/<name>", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.delete(
    "https://app.mailbench.dev/v1/messages/msg_htumcicppd26jek6/tags/<name>",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "removed": "string"
  }
}

List tags in use

GET/v1/tags

Returns a list of

  • namestringrequired
  • colorstringrequired
    A CSS color, or empty for the automatic color.
  • message_countintegerrequired

Errors

401Missing or invalid API key.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl "https://app.mailbench.dev/v1/tags" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/tags", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/tags",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": [
    {
      "name": "billing",
      "color": "#2563eb",
      "message_count": 4
    }
  ]
}

List tag rules

GET/v1/tag-rules

A rule tags matching messages as they arrive.

Query parameters

  • inbox_idstring
    Only rules for this inbox.

Returns a list of

  • idstringrequired
  • workspace_idstring
  • inbox_idstring or null
  • namestringrequired
  • fieldstringrequired
    One of from, to, subject, header, all.
  • patternstringrequired
    A regular expression.
  • tagsarray of stringsrequired
  • activebooleanrequired
  • created_atstring (date-time)required

Errors

401Missing or invalid API key.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl "https://app.mailbench.dev/v1/tag-rules" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/tag-rules", {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.get(
    "https://app.mailbench.dev/v1/tag-rules",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": [
    {
      "id": "trule_ai6monxoyc6e4hcv",
      "workspace_id": "ws_k3m9x2p7qa4d8fbn",
      "inbox_id": null,
      "name": "Billing emails",
      "field": "from",
      "pattern": "billing@",
      "tags": [
        "billing"
      ],
      "active": true,
      "created_at": "2026-10-12T10:00:00Z"
    }
  ]
}

Create a tag rule

POST/v1/tag-rules

Request body

  • inbox_idstring
    Omit to apply to every inbox.
  • namestringrequired
  • fieldstringrequired
    One of from, to, subject, header, all.
  • patternstringrequired
  • tagsarray of stringsrequired
  • activeboolean
    Default true.

Returns

  • idstringrequired
  • workspace_idstring
  • inbox_idstring or null
  • namestringrequired
  • fieldstringrequired
    One of from, to, subject, header, all.
  • patternstringrequired
    A regular expression.
  • tagsarray of stringsrequired
  • activebooleanrequired
  • created_atstring (date-time)required

Errors

400The request was malformed or a value was invalid.
401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X POST "https://app.mailbench.dev/v1/tag-rules" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": "string", "name": "Billing emails", "field": "from", "pattern": "billing@", "tags": [ "billing" ], "active": true}'
const res = await fetch("https://app.mailbench.dev/v1/tag-rules", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "inbox_id": "string",
    "name": "Billing emails",
    "field": "from",
    "pattern": "billing@",
    "tags": [
      "billing"
    ],
    "active": true
  }),
});
const { data } = await res.json();
import os, requests

res = requests.post(
    "https://app.mailbench.dev/v1/tag-rules",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "inbox_id": "string",
        "name": "Billing emails",
        "field": "from",
        "pattern": "billing@",
        "tags": [
            "billing",
        ],
        "active": True,
    },
)
data = res.json()["data"]
Response 201
{
  "success": true,
  "data": {
    "id": "trule_ai6monxoyc6e4hcv",
    "workspace_id": "ws_k3m9x2p7qa4d8fbn",
    "inbox_id": null,
    "name": "Billing emails",
    "field": "from",
    "pattern": "billing@",
    "tags": [
      "billing"
    ],
    "active": true,
    "created_at": "2026-10-12T10:00:00Z"
  }
}

Rename a tag or change its color

PUT/v1/tags/{name}

Renaming applies to every message that has the tag.

Path parameters

  • namestringrequired
    The tag. URL-encode it.

Request body

  • namestring
    The new name. Omit to keep it.
  • colorstring
    A CSS color such as #2563eb. Empty for the automatic color.

Returns

  • old_namestringrequired
  • namestringrequired
  • colorstring

Errors

400The request was malformed or a value was invalid.
401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X PUT "https://app.mailbench.dev/v1/tags/<name>" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "string", "color": "string"}'
const res = await fetch("https://app.mailbench.dev/v1/tags/<name>", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "string",
    "color": "string"
  }),
});
const { data } = await res.json();
import os, requests

res = requests.put(
    "https://app.mailbench.dev/v1/tags/<name>",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "name": "string",
        "color": "string",
    },
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "old_name": "string",
    "name": "string",
    "color": "string"
  }
}

Delete a tag

DELETE/v1/tags/{name}

Removes it from every message. The messages stay.

Path parameters

  • namestringrequired
    The tag. URL-encode it.

Returns

  • deletedstringrequired

Errors

401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X DELETE "https://app.mailbench.dev/v1/tags/<name>" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/tags/<name>", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.delete(
    "https://app.mailbench.dev/v1/tags/<name>",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "deleted": "string"
  }
}

Replace a tag rule

PUT/v1/tag-rules/{id}

Path parameters

  • idstringrequired

Request body

  • inbox_idstring
    Omit to apply to every inbox.
  • namestringrequired
  • fieldstringrequired
    One of from, to, subject, header, all.
  • patternstringrequired
  • tagsarray of stringsrequired
  • activeboolean
    Default true.

Returns

  • idstringrequired
  • workspace_idstring
  • inbox_idstring or null
  • namestringrequired
  • fieldstringrequired
    One of from, to, subject, header, all.
  • patternstringrequired
    A regular expression.
  • tagsarray of stringsrequired
  • activebooleanrequired
  • created_atstring (date-time)required

Errors

400The request was malformed or a value was invalid.
401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X PUT "https://app.mailbench.dev/v1/tag-rules/<id>" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": "string", "name": "Billing emails", "field": "from", "pattern": "billing@", "tags": [ "billing" ], "active": true}'
const res = await fetch("https://app.mailbench.dev/v1/tag-rules/<id>", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "inbox_id": "string",
    "name": "Billing emails",
    "field": "from",
    "pattern": "billing@",
    "tags": [
      "billing"
    ],
    "active": true
  }),
});
const { data } = await res.json();
import os, requests

res = requests.put(
    "https://app.mailbench.dev/v1/tag-rules/<id>",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "inbox_id": "string",
        "name": "Billing emails",
        "field": "from",
        "pattern": "billing@",
        "tags": [
            "billing",
        ],
        "active": True,
    },
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "id": "trule_ai6monxoyc6e4hcv",
    "workspace_id": "ws_k3m9x2p7qa4d8fbn",
    "inbox_id": null,
    "name": "Billing emails",
    "field": "from",
    "pattern": "billing@",
    "tags": [
      "billing"
    ],
    "active": true,
    "created_at": "2026-10-12T10:00:00Z"
  }
}

Delete a tag rule

DELETE/v1/tag-rules/{id}

Messages already tagged keep their tags.

Path parameters

  • idstringrequired

Returns

  • deletedstringrequired

Errors

401Missing or invalid API key.
403The key is read-only, or the action needs a dashboard session.
404No such object in this workspace.
429Too many requests. Wait `Retry-After` seconds.
curl / JavaScript / Python
curl -X DELETE "https://app.mailbench.dev/v1/tag-rules/<id>" \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch("https://app.mailbench.dev/v1/tag-rules/<id>", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
});
const { data } = await res.json();
import os, requests

res = requests.delete(
    "https://app.mailbench.dev/v1/tag-rules/<id>",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
data = res.json()["data"]
Response 200
{
  "success": true,
  "data": {
    "deleted": "string"
  }
}