Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

CURL.SetOptionCustomRequest

Sets a custom request.

Component Version macOS Windows Linux Server iOS SDK
CURL 2.5 ✅ Yes ✅ Yes ✅ Yes ✅ Yes ✅ Yes
MBS( "CURL.SetOptionCustomRequest"; curl; Value { ; Encoding } )   More

Parameters

Parameter Description Example Flags
curl The CURL session handle. $curl
Value The custom request string. "PUT"
Encoding The text encoding for text parameter.
Default is UTF-8.
Possible encoding names: ANSI, ISO-8859-1, Latin1, Mac, Native, UTF-8, DOS, Hex, Base64 or Windows. More listed in the FAQ.		 "utf8" Optional

Result

Returns "OK" on success.

Description

Sets a custom request.
Pass a text string as parameter. It will be used instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST when doing a FTP directory listing. This is useful for doing DELETE or other more or less obscure HTTP requests. Don't do this at will, make sure your server supports the command first.

When you change the request method by setting CURL.SetOptionCustomRequest to something, you don't actually change how libcurl behaves or acts in regards to the particular request method, it will only change the actual string sent in the request.

For example: if you tell libcurl to do a HEAD request, but then change the request to a "GET" with CURL.SetOptionCustomRequest you'll still see libcurl act as if it sent a HEAD even when it does send a GET.

To switch to a proper HEAD, use CURL.SetOptionNoBody, to switch to a proper POST, use CURL.SetOptionPost and CURL.SetOptionPostFields.

Restore to the internal default by setting this to "".

Many people have wrongly used this option to replace the entire request with their own, including multiple headers and POST contents. While that might work in many cases, it will cause libcurl to send invalid requests and it could possibly confuse the remote server badly. Use CURL.SetOptionPost and CURL.SetOptionPostFields to set POST data. Use CURL.SetOptionHTTPHeader to replace or extend the set of headers sent by libcurl. Use CURL.SetOptionHTTPVersion to change HTTP version.

You find a lot of IMAP commands described here:
https://www.atmail.com/blog/imap-commands/

See also CUSTOMREQUEST option in CURL manual.

Examples

Advanced file listing for FTP:

MBS( "CURL.SetOptionCustomRequest"; $curl; "MLSD" )

Set delete request:

MBS( "CURL.SetOptionCustomRequest"; $curl; "DELETE" )

Sets custom request PATCH:

Set Variable [ $r ; Value: MBS( "CURL.SetOptionCustomRequest"; $curl; "PATCH" ) ]
Set Variable [ $r ; Value: MBS( "CURL.SetOptionPostFields"; $curl; $json ) ]

Sets request POST:

MBS( "CURL.SetOptionPost"; $curl; 1 )

POP3: Delete email

#Start new session
Set Variable [$curl; Value:MBS("CURL.New")]
#You can specify the message either in the URL or DELE command
Set Variable [$result; Value:MBS("CURL.SetOptionURL"; $curl; "pop3://pop.monkeybreadsoftware.com/1")]
#put credentials in place
Set Variable [$result; Value:MBS("CURL.SetOptionUserName"; $curl; "xxx@macsw.de")]
Set Variable [$result; Value:MBS("CURL.SetOptionPassword"; $curl; "xxx")]
#Set the DELE command
Set Variable [$result; Value:MBS("CURL.SetOptionCustomRequest"; $curl; "DELE")]
#Do not perform a transfer as DELE returns no data
Set Variable [$result; Value:MBS("CURL.SetOptionNoBody"; $curl; 1)]
#Perform the custom request
Set Field [CURL Test::Result; MBS("CURL.Perform"; $curl)]
#Check result
Set Field [CURL Test::Text; MBS("CURL.GetResultAsText"; $curl; "UTF8")]
Set Field [CURL Test::debug; MBS("CURL.GetDebugMessages"; $curl)]
#Cleanup
Set Variable [$result; Value:MBS("CURL.Release"; $curl)]

POP3: Query capabilities with UIDL request:

// This is a simple example using CURL’s POP3 capabilities to list the contents of a mailbox.
Set Variable [ $curl ; Value: MBS("CURL.New") ]
Set Variable [ $result ; Value: MBS("CURL.SetOptionURL"; $curl; CURL Test::URL) ]
Set Field [ CURL Test::Result ; MBS("CURL.SetOptionCustomRequest"; $curl; "UIDL") ]
Set Field [ CURL Test::Result ; MBS("CURL.SetOptionPassword"; $curl; "xxx") ]
Set Field [ CURL Test::Result ; MBS("CURL.SetOptionUserName"; $curl; "yyy") ]
# Run transfer
Set Field [ CURL Test::Result ; MBS("CURL.Perform"; $curl) ]
# Check result
Set Field [ CURL Test::Text ; MBS("CURL.GetResultAsText"; $curl; "UTF8") ]
Set Field [ CURL Test::header ; MBS("CURL.GetHeaders”; $curl) ]
Set Field [ CURL Test::debug ; MBS("CURL.GetDebugMessages”; $curl) ]
# Cleanup
Set Variable [ $result ; Value: MBS("CURL.Release"; $curl) ]

POP3: Query headers of first email:

# TOP x y
# x = ID of email, starting at 1
# y = number of lines, default all.
Set Variable [ $curl ; Value: MBS("CURL.New") ]
Set Variable [ $result ; Value: MBS("CURL.SetOptionURL"; $curl; CURL Test::URL) ]
Set Field [ CURL Test::Result ; MBS("CURL.SetOptionCustomRequest"; $curl; "TOP 1 0") ]
Set Field [ CURL Test::Result ; MBS("CURL.SetOptionPassword"; $curl; "xxx") ]
Set Field [ CURL Test::Result ; MBS("CURL.SetOptionUserName"; $curl; "yyy") ]
# Run transfer
Set Field [ CURL Test::Result ; MBS("CURL.Perform"; $curl) ]
# Check result
Set Field [ CURL Test::Text ; MBS("CURL.GetResultAsText"; $curl; "UTF8") ]
Set Field [ CURL Test::header ; MBS("CURL.GetHeaders"; $curl) ]
Set Field [ CURL Test::debug ; MBS("CURL.GetDebugMessages”; $curl) ]
# Cleanup
Set Variable [ $result ; Value: MBS("CURL.Release"; $curl) ]

Create folder via WebDAV:

Set Variable [ $r ; Value: MBS("CURL.SetOptionCustomRequest"; $curl; "MKCOL") ]

IMAP: Fetch all email list with MessageID included:

Set Variable [$r; Value:MBS("CURL.SetOptionCustomRequest"; $curl; "FETCH 1:* (FLAGS BODY.PEEK[HEADER.FIELDS (Message-Id)])")]

IMAP: Fetch email flags:

MBS( "CURL.SetOptionCustomRequest"; $curl; "FETCH 1:* FLAGS" )

IMAP: Mark email to be deleted:

Set Variable [$r; Value:MBS("CURL.SetOptionCustomRequest"; $curl; "STORE " & $EmailID & " +FLAGS (\DELETED)")]

# use UID STORE when using UID for email

IMAP: Delete emails marked as to be deleted:

Set Variable [$r; Value:MBS("CURL.SetOptionCustomRequest"; $curl; "EXPUNGE")]

IMAP: Move email:

Set Variable [ $URL ; Value: "imap://" & EmailClient::Server & "/INBOX" ]
Set Variable [ $curl ; Value: MBS("CURL.New") ]
Set Variable [ $r ; Value: MBS("CURL.SetOptionURL"; $curl; $URL) ]
Set Variable [ $r ; Value: MBS("CURL.SetOptionUserName"; $curl; EmailClient::Username) ]
Set Variable [ $r ; Value: MBS("CURL.SetOptionPassword"; $curl; EmailClient::Password) ]
# Move email with UID 1234 to folder test
Set Variable [ $r ; Value: MBS("CURL.SetOptionCustomRequest"; $curl; "UID MOVE 1234 INBOX.test") ]
# Move email 1 in INBOX to folder test
// Set Variable [ $r ; Value: MBS("CURL.SetOptionCustomRequest"; $curl; "MOVE 1 INBOX.test") ]
Set Variable [ $result ; Value: MBS("CURL.Perform"; $curl) ]
Set Variable [ $output ; Value: MBS("CURL.GetResultAsText"; $curl) ]
Set Variable [ $debug ; Value: MBS("CURL.GetDebugMessages"; $curl) ]
Set Field [ EmailClient::ErrorLog ; $debug ]
Set Variable [ $r ; Value: MBS("CURL.Release"; $curl) ]

IMAP: Query quota details:

MBS( "CURL.SetOptionCustomRequest"; $curl; "GETQUOTA" )

IMAP: Query number of messages in the inbox:

MBS( "CURL.SetOptionCustomRequest"; $curl; "STATUS INBOX (MESSAGES)" )

Example result: * STATUS INBOX (MESSAGES 36)

IMAP: Query number of unseen/unread messages in the inbox:

MBS( "CURL.SetOptionCustomRequest"; $curl; "STATUS INBOX (UNSEEN)" )

IMAP: Query number of unseen/unread messages in the mailbox:

MBS( "CURL.SetOptionCustomRequest"; $curl; "STATUS Archive.2016 (MESSAGES)" )
# Mailbox 2016 in Mailbox Archive

IMAP: Search new emails:

MBS( "CURL.SetOptionCustomRequest"; $curl; "SEARCH NEW" )

# Set the SEARCH command specifying what we want to search for. Note that
# this can contain a message sequence set and a number of search criteria
# keywords including flags such as ANSWERED, DELETED, DRAFT, FLAGGED, NEW,
# RECENT and SEEN. For more information about the search criteria please
# see RFC-3501 section 6.4.4.

IMAP: Fetch an email without marking it as seen:

Set Variable [$r; Value:MBS("CURL.SetOptionCustomRequest"; $curl; "UID FETCH " & $UID & " BODY.PEEK[]")]

See also

Example Databases

Blog Entries

Created 18th August 2014, last changed 4th March 2023


CURL.SetOptionCookieSession - CURL.SetOptionDNSCacheTimeout