/gmail/v1/users/{userId}/settings/filters

POST

users

Creates a filter. Note: you can only create a maximum of 1,000 filters.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://gmail.googleapis.com//gmail/v1/users//settings/filters' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": {
        "addLabelIds": [
            "string"
        ],
        "forward": "string",
        "removeLabelIds": [
            "string"
        ]
    },
    "criteria": {
        "excludeChats": true,
        "from": "string",
        "hasAttachment": true,
        "negatedQuery": "string",
        "query": "string",
        "size": 0,
        "sizeComparison": "unspecified",
        "subject": "string",
        "to": "string"
    },
    "id": "string"
}'

Response Example

{
  "action": {
    "addLabelIds": [
      "string"
    ],
    "forward": "string",
    "removeLabelIds": [
      "string"
    ]
  },
  "criteria": {
    "excludeChats": true,
    "from": "string",
    "hasAttachment": true,
    "negatedQuery": "string",
    "query": "string",
    "size": 0,
    "sizeComparison": "unspecified",
    "subject": "string",
    "to": "string"
  },
  "id": "string"
}

Request

Path Params

userId

string

required

User's email address. The special value "me" can be used to indicate the authenticated user.

Body Params application/json

Resource definition for Gmail filters. Filters apply to specific messages instead of an entire email thread.

action

object (FilterAction)

optional

Action that the filter performs.

addLabelIds

array[string]

optional

List of labels to add to the message.

forward

string

optional

Email address that the message should be forwarded to.

removeLabelIds

array[string]

optional

List of labels to remove from the message.

criteria

object (FilterCriteria)

optional

Matching criteria for the filter.

excludeChats

boolean

optional

Whether the response should exclude chats.

from

string

optional

The sender's display name or email address.

hasAttachment

boolean

optional

Whether the message has any attachment.

negatedQuery

string

optional

Only return messages not matching the specified query. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid: is:unread".

query

string

optional

Only return messages matching the specified query. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid: is:unread".

size

integer <int32>

optional

The size of the entire RFC822 message in bytes, including all headers and attachments.

sizeComparison

enum<string>

optional

How the message size in bytes should be in relation to the size field.

Allowed values:

unspecifiedsmallerlarger

subject

string

optional

Case-insensitive phrase found in the message's subject. Trailing and leading whitespace are be trimmed and adjacent spaces are collapsed.

string

optional

The recipient's display name or email address. Includes recipients in the "to", "cc", and "bcc" header fields. You can use simply the local part of the email address. For example, "example" and "example@" both match "example@gmail.com". This field is case-insensitive.

string

optional

The server assigned ID of the filter.

Examples

Responses

🟢200Successful response

application/json

Body

Resource definition for Gmail filters. Filters apply to specific messages instead of an entire email thread.

action

object (FilterAction)

optional

Action that the filter performs.

addLabelIds

array[string]

optional

List of labels to add to the message.

forward

string

optional

Email address that the message should be forwarded to.

removeLabelIds

array[string]

optional

List of labels to remove from the message.

criteria

object (FilterCriteria)

optional

Matching criteria for the filter.

excludeChats

boolean

optional

Whether the response should exclude chats.

from

string

optional

The sender's display name or email address.

hasAttachment

boolean

optional

Whether the message has any attachment.

negatedQuery

string

optional

Only return messages not matching the specified query. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid: is:unread".

query

string

optional

Only return messages matching the specified query. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid: is:unread".

size

integer <int32>

optional

The size of the entire RFC822 message in bytes, including all headers and attachments.

sizeComparison

enum<string>

optional

How the message size in bytes should be in relation to the size field.

Allowed values:

unspecifiedsmallerlarger

subject

string

optional

Case-insensitive phrase found in the message's subject. Trailing and leading whitespace are be trimmed and adjacent spaces are collapsed.

string

optional

string

optional

The server assigned ID of the filter.

Modified at 2023-08-15 05:40:23

/gmail/v1/users/{userId}/settings/filters

/gmail/v1/users/{userId}/settings/filters/{id}