wp_remote_post( string $url, array $args = array() ): array|WP_Error

Performs an HTTP request using the POST method and returns its response.

Description

See also

Parameters

$urlstringrequired
URL to retrieve.
$argsarrayoptional
Request arguments.
See WP_Http::request() for information on accepted arguments.

Default:array()

Return

array|WP_Error The response or WP_Error on failure.

Source

function wp_remote_post( $url, $args = array() ) {
	$http = _wp_http_get_object();
	return $http->post( $url, $args );
}

Changelog

VersionDescription
2.7.0Introduced.

User Contributed Notes

  1. Skip to note 9 content

    Post data should be sent in the body as an array. Example passing post data:

    $response = wp_remote_post( $url, array(
    	'method'      => 'POST',
    	'timeout'     => 45,
    	'redirection' => 5,
    	'httpversion' => '1.0',
    	'blocking'    => true,
    	'headers'     => array(),
    	'body'        => array(
    		'username' => 'bob',
    		'password' => '1234xyz'
    	),
    	'cookies'     => array()
        )
    );
    
    if ( is_wp_error( $response ) ) {
    	$error_message = $response->get_error_message();
    	echo "Something went wrong: $error_message";
    } else {
    	echo 'Response:<pre>';
    	print_r( $response );
    	echo '</pre>';
    }

    In the example above, $response['body'] will contain the actual page content returned by the server.

  2. Skip to note 10 content

    An example of a JSON body:

    $endpoint = 'api.example.com';
    
    $body = [
    	'name'  => 'Pixelbart',
    	'email' => 'pixelbart@example.com',
    ];
    
    $body = wp_json_encode( $body );
    
    $options = [
    	'body'        => $body,
    	'headers'     => [
    		'Content-Type' => 'application/json',
    	],
    	'timeout'     => 60,
    	'redirection' => 5,
    	'blocking'    => true,
    	'httpversion' => '1.0',
    	'sslverify'   => false,
    	'data_format' => 'body',
    ];
    
    wp_remote_post( $endpoint, $options );
  3. Skip to note 13 content

    A couple notes I thought worth mentioning is that if you’re using a WordPress API endpoint that requires authentication, you can pass the _wpnonce parameter along with the session cookies to properly authenticate, like so:

    $endpoint = get_rest_url( null, 'ninja-forms-submissions/submissions/get' );
    $body = array(
    	'_wpnonce' => wp_create_nonce( 'wp_rest' ),
    	'type' => 'columns',
    	'form_ids' => '1'
    );
    
    // Need session cookies passed to verify nonce
    $cookies = array();
    foreach ( $_COOKIE as $name => $value ) {
        $cookies[] = new WP_Http_Cookie( array( 'name' => $name, 'value' => $value ) );
    }
    
    $options = array(
    	'method'.     => 'GET',
    	'body'        => $body,
    	'headers'     => array(
    		'Cache-Control' => 'no-cache',
    	),
    	'timeout'     => 60,
    	'redirection' => 5,
    	'blocking'    => true,
    	'httpversion' => '1.0',
    	'sslverify'   => false,
    	'data_format' => 'body',
    	'cookies'     => $cookies
    );
    
    $response = wp_remote_post( $endpoint, $options );

    Note that I’m also using wp_remote_post to perform a GET call in this example (by passing the ‘method’ argument), otherwise I could use the wp_remote_get function instead

  4. Skip to note 14 content

    Handle errors using is_wp_error() as follows:

    $args = array(
        'headers' => array(
            'Authorization' => 'Bearer 123hash',
            'Content-Type' => 'application/json',
        ),
        'timeout' => 0.001, // This should give you a timeout error, unless you are hitting something spectacularly fast
        'body' => json_encode( array( 'blah' => 'yack' ) ),
    );
    
    $response = wp_remote_post( 'https://developer.wordpress.org', $args );
    
    if ( ! is_wp_error( $response ) ) {
        $body = json_decode( wp_remote_retrieve_body( $response ), true );
        return $body;
    } else {
        $error_message = $response->get_error_message();
        throw new Exception( $error_message );
    }

You must log in before being able to contribute a note or feedback.