I need help on how to add several custom email headers when sending email using GAE's Mail API (Python) i.e. Message-id, person-id and etc.

But somehow, I don't see it in the documentation: https://cloud.google.com/appengine/docs/standard/python/refdocs/google.appengine.api.mail

I can receive emails and read custom email headers using the method below: mail_message.original.getitem('mail_header')

But I don't know how to send an email with custom email headers.

Here is the code i use to send email:

mail.send_mail(sender=sender_address,
               to="handsome_me@yahoo.com",
               subject="gwapo",
               body="Hi")

Looks like you missed this line in the docs:

PROPERTIES = set(['body', 'amp_html', 'sender', 'to', 'cc', 'bcc', 'attachments', 'headers', 'html', 'reply_to', 'subject'])

You can provide a headers parameter containing a list of custom headers.

Looking at the sources, the headers paramenter is subject to the following restrictions:

• must be a dict
• all values must be strings
• all keys must be ASCII
• key should be in the following white list: Auto-Submitted, In-Reply-To, List-Id, List-Unsubscribe, On-Behalf-Of, References, Resent-Date, Resent-From, Resent-To.

I'm afraid you won't be able to override message-id using AppEngine as it is not in the HEADERS_WHITELIST. I forgot how crippled AppEngine is, you may want to check third-party email services. I've used mailgun and they allow arbitrary headers as long as they are prefixed by X- (just include a h:X-My-Arbitrary-Header in the payload). From the AppEngine docs:

Sending Messages with Third-Party Services

Python 2.7/3.7 |Java 8/11 |PHP 5/7 |Ruby |Go 1.9/1.11/1.12 |Node.js Python 3.7 applications on App Engine can use third-party companies to send email, SMS messages, or make and receive phone calls. For example, you might send email to confirm business transactions, confirm the creation of user accounts, or send marketing communications.

This page lists some examples of companies that provide communication services and client libraries for Python 3.7 applications on App Engine.

Note: The services offered by these third-party companies are not covered by the App Engine Service Level Agreement.

Mailgun

Mailgun provides both RESTful APIs and client libraries for sending email. As a GCP project user, your first 30,000 messages are free every month. See the monthly pricing calculator on the sign up page for pricing on additional messages and volume discounts.

Learn more about Mailgun:

• Mailgun developer documentation
• Mailgun client libraries

...

SendGrid

You can use SendGrid to power your emails on App Engine. SendGrid can improve your deliverability and provide transparency into what actually happens to those emails your app sends. You can see statistics on opens, clicks, unsubscribes, spam reports and more with the SendGrid interface or its API.

App Engine customers can send 12,000 emails every month for free by signing up for the SendGrid Email API plan through the Google Cloud Platform Console. Note that Google is compensated for customers who sign up for a paid account.

Learn more about SendGrid:

• SendGrid developer documentation
• SendGrid client libraries

I'm not affiliated with any of those and the original page mentions other services, I'm quoting mailgun because I've used it and know it works, and sendgrid because it is mentioned by OP.