How to send a message successfully using the new Gmail REST API?

Note: This is a PHP specific answer, but I'm sure some of you will find it useful.

In case you're struggling with setting up the raw data correctly in PHP as I did, using PHPMailer would make things cleaner and easier for you.

After including the library in your code (if you use composer, just add "phpmailer/phpmailer": "~5.2" in the require section of your composer.json), you set the basic details:

$mail = new PHPMailer();
$mail->From = 'FROM_EMAIL';
$mail->FromName = 'FROM_NAME';
$mail->addAddress('TO_EMAIL','TO_NAME');
$mail->Subject = 'EMAIL_SUBJECT';
$mail->Body = 'EMAIL_BODY';
$mail->preSend(); 
$mime = $mail->getSentMIMEMessage();

Now you can base64 encode the $mime to get the raw string for the Gmail API. Use this instead of simple base64_encode, in order to get a valid web safe encoded string. rtrim(strtr(base64_encode($mime), '+/', '-_'), '=');

This worked for me

Url: https://www.googleapis.com/upload/gmail/v1/users/me/messages/send (POST Method)

InHeaders:- "Authorization " : "Bearer ya29.Il-iBylW9AUr6V0QO72ryo17r7hf8i5zh8dU63ZjDNaxAApumh6T7lh20my_DQZomtL_qokZnJEgapYN20LmdlG6lFbqGASL5lqFAKnOoUtZA992JwOlUQxMVW6_Yto7jQ", "Content-Type" : "message/rfc822"

InBody:-

{"raw": "From: <[email protected]> 
To: <[email protected]> 
Subject: Saying Hello
This is a message just to say hello. So, "Hello"."}

got it!

after reading the RFC 2822 specification I found out, that the complete message needs to be passed in the raw parameter, see the example:

From: John Doe <[email protected]> 
To: Mary Smith <[email protected]> 
Subject: Saying Hello 
Date: Fri, 21 Nov 1997 09:55:06 -0600 
Message-ID: <[email protected]>

This is a message just to say hello. So, "Hello".

So after base64 encoding the complete message, passing it in the raw parameter without using any other parameter, it works fine.

Edit 1:
As @Amit mentioned, it must be web-safe base64 encoded, see also https://code.google.com/p/stringencoders/wiki/WebSafeBase64

So to convert the base64 alpha into a format that is "web-safe" the following changes are recommended:

+ --> - (char 62, plus to dash)
/ --> _ (char 63, slash to underscore)
= --> * padding

To only convert + to - and /to _ was sufficient for me.

Edit 2:
To answer the question of @Hjulle here an example: you only need the userId and in the request body the raw parameter. Let's assume, your email address is [email protected]

First Base64 encode the complete message (see above) using an online encoder and you get this string:

RnJvbTogSm9obiBEb2UgPGpkb2VAbWFjaGluZS5leGFtcGxlPiAKVG86IE1hcnkgU21pdGggPG1h
cnlAZXhhbXBsZS5uZXQ+IApTdWJqZWN0OiBTYXlpbmcgSGVsbG8gCkRhdGU6IEZyaSwgMjEgTm92
IDE5OTcgMDk6NTU6MDYgLTA2MDAgCk1lc3NhZ2UtSUQ6IDwxMjM0QGxvY2FsLm1hY2hpbmUuZXhh
bXBsZT4KClRoaXMgaXMgYSBtZXNzYWdlIGp1c3QgdG8gc2F5IGhlbGxvLiBTbywgIkhlbGxvIi4=

Now convert + to - and /to _ and you get

RnJvbTogSm9obiBEb2UgPGpkb2VAbWFjaGluZS5leGFtcGxlPiAKVG86IE1hcnkgU21pdGggPG1h
cnlAZXhhbXBsZS5uZXQ-IApTdWJqZWN0OiBTYXlpbmcgSGVsbG8gCkRhdGU6IEZyaSwgMjEgTm92
IDE5OTcgMDk6NTU6MDYgLTA2MDAgCk1lc3NhZ2UtSUQ6IDwxMjM0QGxvY2FsLm1hY2hpbmUuZXhh
bXBsZT4KClRoaXMgaXMgYSBtZXNzYWdlIGp1c3QgdG8gc2F5IGhlbGxvLiBTbywgIkhlbGxvIi4=

Now pass this in the raw parameter of the API Explorer.