Skip to main content

API - (Part 6) - Quarantine Resource

API Documentation:

Domain Quarantine

Endpoint: /api/v1/domain/{pk}/quarantine/

Endpoint: /api/v1/domain/{domain_name}/quarantine/

Method: GET

Parameters:

Url placeholders:

  • pk (required): The primary key of the domain for which to retrieve quarantine messages.
  • domain_name (required): The name of the domain for which to retrieve quarantine messages.

GET params, one of these params are always required in request:

  • content: Filter the messages by content type. Possible values are 'S' for spam, 'V' for virus, 'B' for banned, 'M' for Bad MIME, and 'U' for unchecked, 'H' for bad header.
  • rs: Filter the messages by whether they have been recovered (R) or deleted (D).
  • bl: Filter the messages by whether they have been blocked (BL).

Response message format

{
  "bl": "N",
  "bspam_level": 0,
  "content": "S",
  "date": "08 May 2012, 05:11 AM",
  "ds": "D",
  "envelope_sender": "sender4@spam.com",
  "from_addr": "no-reply@asdf.com",
  "id": "KYd65PytAGrw45;21;1",
  "message": "/api/v1/quarantine_message/KYd65PytAGrw45/21/",
  "partition_tag": 21,
  "recipient": "u1@usercase.com",
  "resource_uri": "/api/v1/quarantine/KYd65PytAGrw45;21;1/",
  "rs": "",
  "rseqnum": 1,
  "size": 2296,
  "spam_level": 0,
  "subject": "this is test subject
}

Where

  • bl: Whether the message has been blocked by block list. Possible values are 'N' for not blocked, 'Y' for blocked
  • spam_level: The spam level of the message
  • content: The content type of the message. Possible values are 'S' for spam, 'V' for virus, 'B' for banned, 'M' for Bad MIME, and 'U' for unchecked, 'H' for bad header.
  • date: The date the message was received
  • ds: Delivery status P/R/B/D/T - pass/reject/bounce/discard/tempfail
  • envelope_sender: The envelope sender of the message
  • from_addr: The from address of the message
  • message: The URI of the full message with body and headers
  • recipient: The recipient of the message
  • resource_uri: The URI of this quarantine item
  • rs: Recovery status R/D - recovered/deleted
  • rseqnum: The sequence number of the message (used to fetch full message)
  • size: The size of the message in bytes
  • subject: The subject of the message

Examples

To fetch Spam messages for domain "example.com":

GET /api/v1/domain/example.com/quarantine/?content__in=S,H

Response:

{
  "meta": {
    "limit": 10,
    "next": "/api/v1/quarantine/?content__in=S%2CH&limit=10&offset=10",
    "offset": 0,
    "previous": null,
    "total_count": 31
  },
  "objects": [
    {
      "bl": "N",
      "bspam_level": 0,
      "content": "S",
      "date": "08 May 2012, 05:11 AM",
      "ds": "D",
      "envelope_sender": "sender4@spam.com",
      "from_addr": "no-reply@asdf.com",
      "id": "KYd65PytAGrw45;21;1",
      "message": "/api/v1/quarantine_message/KYd65PytAGrw45/21/",
      "partition_tag": 21,
      "recipient": "u1@usercase.com",
      "resource_uri": "/api/v1/quarantine/KYd65PytAGrw45;21;1/",
      "rs": "",
      "rseqnum": 1,
      "size": 2296,
      "spam_level": 0,
      "subject": "this is test subject"
    },
...

To fetch Visus messages for domain "example.com":

GET /api/v1/domain/example.com/quarantine/?content=V

To fetch deleted messages for domain "example.com":

GET /api/v1/domain/example.com/quarantine/?rs=D

To fetch blocked messages for domain "example.com":

GET /api/v1/domain/example.com/quarantine/?bl=BL

Delete a message from quarantine

Endpoint: /api/v1/quarantine/{id}/

Method: DELETE

resource_url of quarantine item can be used to delete a message from quarantine.

id: is composite key of quarantine item. E.g. "KYd65PytAGrw45;21;1" from the item above.

Delete messages from quarantine

Endpoint: /api/v1/quarantine/mass_delete/

Method: POST

Body: JSON of the following format {"id__in":"<comma separated list of quarantine item ids>"}

Example:

POST /api/v1/quarantine/mass_delete/
{
  "id__in": "KYd65PytAGrw45;21;1,KYd65PytAGrw45;21;2"
}

Response: empty response with 204 status code.

Recover messages from quarantine

Endpoint: /api/v1/quarantine/mass_recover/

Method: POST

Body: JSON of the following format {"id__in":"<single id or comma separated list of quarantine item ids>"}

Example:

POST /api/v1/quarantine/mass_recover/
{
  "id__in": "KYd65PytAGrw45;21;1,KYd65PytAGrw45;21;2"
}

Adding sender to allow list

Endpoint: /api/v1/quarantine/mass_whitelist_sender/email/{destination}/

Method: POST

Body: JSON of the following format {"id__in":"<single id or comma separated list of quarantine item ids>"}

Where destination can be emailaccount if sender need to be added to recipient's allow list or domain if sender need to be added to domain's allow list.

GET or POST params:

recover: If set to true, the message will be recovered from quarantine after adding to allow list. Default is false.

Examples

Add 2 senders to recipient's allow list and recover the message:

POST /api/v1/quarantine/mass_whitelist_sender/email/emailaccount/?recover=true
{
  "id__in": "KYd65PytAGrw45;21;1,KYd65PytAGrw45;21;2"
}

Add 2 senders to domain's allow list:

POST /api/v1/quarantine/mass_whitelist_sender/email/domain/
{
  "id__in": "KYd65PytAGrw45;21;1,KYd65PytAGrw45;21;2"
}

Fetchch full message from quarantine

Full message will contain full headers and body of the message.

Endpoint: /api/v1/quarantine_message/{id}/{partition_tag}/?rseqnum={rseqnum}

Method: GET

Use message uri field of quarantine item to fetch full message. Must pass rseqnum as query parameter.

Example:

GET /api/v1/quarantine_message/KYd65PytAGrw45/21/?rseqnum=1

Response:

{
"attachments": {},
"bspam_level": -1.839,
"content": "S",
"envelope_sender": "sender@example.com",
"from_addr": "sender@example.com",
"from_addr_domain": "example.com",
"headers": [
    [
        "X-Envelope-To",
        "<recipient_email@domain.net>"
    ],
    [
        "X-Envelope-To-Blocked",
        "<recipient_email@domain.net>"
    ],
    [
        "X-Quarantine-ID",
        "<r1aHkMo5MXzF>"
    ],
    [
        "X-Spam-Flag",
        "YES"
    ],
    [
        "X-Spam-Score",
        "-1.839"
    ],
    [
        "X-Spam-Level",
        ""
    ],
    [
        "X-Spam-Status",
        "Yes, score=-1.839 tag=-9999 tag2=-86.9 kill=-85.1\n\ttests=[BAYES_00=-1.9, DKIM_SIGNED=-0.1, DKIM_VALID=-0.01,\n\tDKIM_VALID_AU=-0.01, DKIM_VALID_EF=-0.1, DKIM_VERIFIED=-0.01,\n\tDMARC_PASS=-0.01, ENA_FREEMAIL=0.2, FREEMAIL_FROM=0.001, JOE_JOB=0.1,\n\tJ_CONFIRM=0.1, MR_RCVD_TLS=-0.1, OPEN_DKIM_PASS=-0.01,\n\tRELAYCOUNTRY_NORTHERN_AMERICA=0.01, RELAYCOUNTRY_US=0.01,\n\tSPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01]\n\tautolearn=no autolearn_force=no"
    ],
    [
        "X-Spam-Language",
        ""
    ],
    [
        "X-Spam-Relay-Countries",
        "US XX"
    ],
    [
        "Authentication-Results",
        "003.mia (mroute_mailscanner); dkim=pass (2048-bit key)\n\theader.d=example.com"
    ],
    [
        "Received",
        "from in-003.mia.mailroute.net ([199.89.3.6])\n\tby localhost (003.mia [127.0.0.1]) (mroute_mailscanner, port 10024)\n\twith LMTP id r1aHkMo5MXzF for <recipient_email@domain.net>;\n\tFri, 24 Mar 2023 14:35:27 +0000 (UTC)"
    ],
    [
        "Received",
        "from mail-lf1-f42.google.com (mail-lf1-f42.google.com [209.85.167.42])\n\t(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby in-003.mia.mailroute.net (Postfix) with ESMTPS id 4Pjl9p1D4rz23kR7\n\tfor <recipient_email@domain.net>; Fri, 24 Mar 2023 14:35:25 +0000 (UTC)"
    ],
    [
        "Authentication-Results",
        "mail.mailroute.net; dmarc=pass (p=none dis=none) header.from=example.com"
    ],
    [
        "Authentication-Results",
        "mail.mailroute.net; spf=pass smtp.mailfrom=sender@example.com"
    ],
    [
        "Authentication-Results",
        "mail.mailroute.net;\n\tdkim=pass (2048-bit key) header.d=example.com header.i=@example.com header.b=\"Fw9KAr9x\""
    ],
    [
        "Received",
        "by mail-lf1-f42.google.com with SMTP id h25so2489568lfv.6\n        for <recipient_email@domain.net>; Fri, 24 Mar 2023 07:35:27 -0700 (PDT)"
    ],
    [
        "DKIM-Signature",
        "v=1; a=rsa-sha256; c=relaxed/relaxed;\n        d=example.com; s=20210112; t=1679668524;\n        h=to:date:message-id:subject:mime-version:content-transfer-encoding\n         :from:from:to:cc:subject:date:message-id:reply-to;\n        bh=/LU9D2F1qG54kdwhiW52a4aNcxtq233nu2ICcb94bpM=;\n        b=Fw9KAr9xH+qW95uyChB6bzKlMYM6ALnfcTZXW+ImNL63RVzWtY3EnzxkV8XTVPOof1\n         xYMtZtFHb2PBqqPML+ZAbDZFmqZSD8sJUdm+ajFn1hpS9Q9sqpKuXJQ7gtMalu91deBy\n         lIry3sMneIAn6mQEiAtZstUtObDHQQNyVXKBBjw4XxVA8Oh1zDjUBBA+UlA8UQXcOSFb\n         RkdfuFH02+OgOw0waZ0l2leTvCTA1vrsO8SFX6xY5UWOBIKb6/I4+sojB4Az3Kf91A1f\n         9sG2YdNx+0EgGwYc5KatquKTB5JVfzGh2OBW1JX3qQZIfegzXT82FWc4KMrPNT7M23vf\n         T/KA=="
    ],
    [
        "X-Google-DKIM-Signature",
        "v=1; a=rsa-sha256; c=relaxed/relaxed;\n        d=1e100.net; s=20210112; t=1679668524;\n        h=to:date:message-id:subject:mime-version:content-transfer-encoding\n         :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to;\n        bh=/LU9D2F1qG54kdwhiW52a4aNcxtq233nu2ICcb94bpM=;\n        b=NWrSgdIq+l8NDNsVG/lC9l9B/rOf45U3WD61+80PuU/UbZRpPxd2ZlXZrGuUlCtlOE\n         C2rs5KnIRkXMKmekbHtm42KwCoV9qBB93lvpIivS4uIGey/cBpLewef8uRBYoZQLolSV\n         oSs5saWYJO8qqyuJGmYUFfevO/meiLc+gGV82/+0ekNCWAoXbOhWiLw7NepG8kPb9weV\n         yBGRhoJIgwkQa7LHLoGc2/OCPXTRFBifpKKTky/1mRvPftLDj989lRmvxtoND/HBCpkJ\n         DG5mSSHDCKVaCys3fccEgBiGViGpWZX9HJqxuGWUy+5haYZusqOAdAPr1MHyCJtCA1GF\n         sUnQ=="
    ],
    [
        "X-Gm-Message-State",
        "AAQBX9e/j0rwWUyU4qQ6YyFD9zyeChJwYitplLlnPlymw8JkyChD/RKy\n\t8m9WRPLnq5+Mn7fLPWZHslcfaMvEnHI="
    ],
    [
        "X-Google-Smtp-Source",
        "AKy350aeqajQ98I3Zb62NbUg4DKwOVO30ts2mN5C9DQR8ui1JuU0kMjA8eR0UW6xtZHx4wY/LoKWTw=="
    ],
    [
        "X-Received",
        "by 2002:ac2:52b5:0:b0:4c0:91d0:e7ad with SMTP id r21-20020ac252b5000000b004c091d0e7admr884627lfm.26.1679668523661;\n        Fri, 24 Mar 2023 07:35:23 -0700 (PDT)"
    ],
    [
        "Received",
        "from smtpclient.apple ([2a02:a31c:35e:9b80:e524:1405:ba74:54a7])\n        by smtp.example.com with ESMTPSA id q4-20020ac25284000000b004e1b880ba20sm3380919lfm.292.2023.03.24.07.35.22\n        for <recipient_email@domain.net>\n        (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128);\n        Fri, 24 Mar 2023 07:35:22 -0700 (PDT)"
    ],
    [
        "From",
        "Vladislav <sender@example.com>"
    ],
    [
        "Content-Type",
        "text/plain;\n\tcharset=us-ascii"
    ],
    [
        "Content-Transfer-Encoding",
        "7bit"
    ],
    [
        "Mime-Version",
        "1.0 (Mac OS X Mail 16.0 \\(3731.400.51.1.1\\))"
    ],
    [
        "Subject",
        "test message"
    ],
    [
        "Message-Id",
        "<F36B9545-4ED4-4640-85DD-2AA3208DA097@example.com>"
    ],
    [
        "Date",
        "Fri, 24 Mar 2023 17:35:11 +0300"
    ],
    [
        "To",
        "Vladislav Knopach <recipient_email@domain.net>"
    ],
    [
        "X-Mailer",
        "Apple Mail (2.3731.400.51.1.1)"
    ]
],
"id": "r1aHkMo5MXzF/14",
"payload": {
    "text/plain": "Test message that should go to spam.\n"
},
"recipient": "recipient_email@domain.net",
"resource_uri": "/api/v1/quarantine_message/r1aHkMo5MXzF/14/",
"spam_level": -1.839,
"subject": "test message",
"when": "Fri, 24 Mar 2023 14:35:11 +0000"
}

Email Account Quarantine

Endpoint: /api/v1/email_account/{pk}/quarantine/

Endpoint: /api/v1/email_account/{email}/quarantine/

Method: GET

Parameters:

Url placeholders:

  • pk (required): The primary key of the email account for which to retrieve quarantine messages.

or

  • email (required): Email of account for which to retrieve quarantine messages.

GET params, one of these params are always required in request:

  • content: Filter the messages by content type. Possible values are 'S' for spam, 'V' for virus, 'B' for banned, 'M' for Bad MIME, and 'U' for unchecked, 'H' for bad header.
  • rs: Filter the messages by whether they have been recovered (R) or deleted (D).
  • bl: Filter the messages by whether they have been blocked (BL).

Response message format

{
  "bl": "N",
  "bspam_level": 0,
  "content": "S",
  "date": "08 May 2012, 05:11 AM",
  "ds": "D",
  "envelope_sender": "sender4@spam.com",
  "from_addr": "no-reply@asdf.com",
  "id": "KYd65PytAGrw45;21;1",
  "message": "/api/v1/quarantine_message/KYd65PytAGrw45/21/",
  "partition_tag": 21,
  "recipient": "u1@usercase.com",
  "resource_uri": "/api/v1/quarantine/KYd65PytAGrw45;21;1/",
  "rs": "",
  "rseqnum": 1,
  "size": 2296,
  "spam_level": 0,
  "subject": "this is test subject
}

Where

  • bl: Whether the message has been blocked by block list. Possible values are 'N' for not blocked, 'Y' for blocked
  • spam_level: The spam level of the message
  • content: The content type of the message. Possible values are 'S' for spam, 'V' for virus, 'B' for banned, 'M' for Bad MIME, and 'U' for unchecked, 'H' for bad header.
  • date: The date the message was received
  • ds: Delivery status P/R/B/D/T - pass/reject/bounce/discard/tempfail
  • envelope_sender: The envelope sender of the message
  • from_addr: The from address of the message
  • message: The URI of the full message
  • recipient: The recipient of the message
  • resource_uri: The URI of quarantine item (differs from full message)
  • rs: Recovery status R/D - recovered/deleted
  • rseqnum: The sequence number of the message
  • size: The size of the message in bytes
  • subject: The subject of the message

Examples

To fetch Spam messages for account "user@example.com":

GET /api/v1/email_account/user@example.com/quarantine/?content__in=S,H

Response:

{
  "meta": {
    "limit": 10,
    "next": "/api/v1/quarantine/?content__in=S%2CH&limit=10&offset=10",
    "offset": 0,
    "previous": null,
    "total_count": 31
  },
  "objects": [
    {
      "bl": "N",
      "bspam_level": 0,
      "content": "S",
      "date": "08 May 2012, 05:11 AM",
      "ds": "D",
      "envelope_sender": "sender4@spam.com",
      "from_addr": "no-reply@asdf.com",
      "id": "KYd65PytAGrw45;21;1",
      "message": "/api/v1/quarantine_message/KYd65PytAGrw45/21/",
      "partition_tag": 21,
      "recipient": "u1@usercase.com",
      "resource_uri": "/api/v1/quarantine/KYd65PytAGrw45;21;1/",
      "rs": "",
      "rseqnum": 1,
      "size": 2296,
      "spam_level": 0,
      "subject": "this is test subject"
    },
...

To fetch Visus messages for account "user@example.com":

GET /api/v1/email_account/user@example.com/quarantine/?content=V

To fetch deleted messages for account "user@example.com":

GET /api/v1/email_account/user@example.com/quarantine/?rs=D

To fetch blocked messages for account "user@example.com":

GET /api/v1/email_account/user@example.com/quarantine/?bl=BL

Related articles

Comments

0 comments

Please sign in to leave a comment.