Gmail App Passwords, IMAP and the API: Three Ways In, and When Each Works
Most Gmail connection problems end at the same place: you need an app password, and you cannot create one until two-factor is on. Here is where that fits among the three ways a script or client can actually reach a mailbox.
Avery Bennett
The most common Gmail problem is not a Gmail problem. A client or a script is given the account password, the connection is refused, and the obvious conclusion is that the password is wrong. It is not. Google stopped accepting account passwords from mail clients, and what it wants instead is an app password.
App passwords, and the prerequisite nobody mentions
An app password is a separate credential, generated inside the account, that a single client uses in place of the login password. Three things about it explain nearly every "not working" search:
- You cannot create one until two-factor authentication is enabled. This is the answer to most of them. The option to generate an app password is simply not present on an account without a second factor, so people look for a page that is not there yet. Turn on two-factor first and the option appears.
- It is shown once. Generated, displayed, and not retrievable afterwards. Losing it means generating another rather than looking it up.
- It is displayed with spaces and entered without them. Sixteen characters in four groups. Some clients cope with the spaces and some do not, and this alone accounts for a fair share of failures on a password that is otherwise correct.
They are generated under the security section of the Google account, not inside Gmail's own settings, which is the other reason people cannot find the page.
If you bought an account and the listing mentions an app password, that string is what goes into the client. The account's login password will not work there, and trying it repeatedly is how you attract additional verification you did not want.
The three ways in
Web sign-in
A browser, a password, a second factor if one is set. Fine for a person, poor for a script. Automated sign-in through the web flow runs into challenges, unfamiliar-device prompts and sometimes phone verification, because that flow is watched for exactly this pattern. When a script "cannot log in" but the credentials are correct, this mismatch is usually why.
IMAP and SMTP
The mail protocols, spoken by every mail client and every mail library. Needs the app password described above. Best for reading a mailbox, waiting on a message, or sending, without building anything.
Practical settings: IMAP on 993 with SSL, SMTP on 587 with STARTTLS, and the full address as the username. Note that IMAP access can be off by default on some accounts and enabled in Gmail's own settings, which is a separate switch from the app password and is worth checking when the credential is definitely right.
The Gmail API
A proper programmatic interface reached through OAuth2. You register a project, configure an OAuth client, complete a consent flow once, and receive tokens your program uses thereafter.
Two real advantages over IMAP: permissions are scoped, so a program can be given read-only access rather than full control, and you get structured message data instead of parsing raw mail. Two real costs: the setup is genuinely more work, and consent screens have their own review rules depending on what you ask for.
Use it for something you are building and maintaining. For reading a code out of an inbox, IMAP is the proportionate answer.
Choosing, in one line each
- A person checking mail: the web, or any client over IMAP.
- A script reading messages: IMAP with an app password. Least setup, works everywhere.
- Software you are building: the API, for scoped permissions and structured data.
- A script driving the web interface: avoid. The friction you meet is deliberate and will not go away.
What this means when buying a mailbox
Two fields on a listing map onto the above, and they are not the same thing.
An app password included means the two-factor-plus-generation work is already done and you can connect a client immediately. An OAuth2 delivery is the API route, and there completeness is what matters: a refresh token without the client id and secret it was issued against will work until the current access token expires and then stop permanently. That failure arrives long after any warranty window closes, so the check is not "does it connect now" but "can I complete a refresh".
Worth knowing on price: across the email catalogue, protocol access is among the cheapest attributes measured while verification attributes such as two-factor and SMS verification are the dearest, at roughly three times the middle price and near three times respectively. Access is cheap; being verified is not.
Gmail listings, with the app password and OAuth2 tags filterable, are on the Gmail shelf.
Frequently Asked Questions
Almost always because two-factor authentication is not enabled on the account. The option to generate an app password does not appear until it is, so the page people are looking for genuinely does not exist yet. Enable two-factor and it appears, under the security section of the Google account rather than inside Gmail settings.
Three usual causes. It is entered with the spaces it was displayed with, and some clients will not accept those. It was generated but never recorded, and it cannot be retrieved afterwards, only replaced. Or IMAP access is switched off in Gmail’s own settings, which is a separate control from the credential and produces a failure that looks identical.
No. Google stopped accepting account passwords from mail clients, which is why the failure reads like a wrong password when the password is correct. An app password is the intended replacement, and repeatedly retrying the login password tends to attract additional verification rather than access.
IMAP for anything that reads or sends mail, because an app password is the only setup and every mail library supports it. The API for software you are building and maintaining, where scoped permissions and structured message data are worth the project registration and consent flow.
Because that flow is watched for automated sign-in and responds with challenges, unfamiliar-device prompts and sometimes phone verification. The credentials are usually fine; the route is wrong. Use IMAP or the API, both of which are intended for programmatic access.
IMAP on port 993 with SSL, SMTP on port 587 with STARTTLS, the full email address as the username, and the app password rather than the account password. If the credential is definitely right and it still fails, check whether IMAP is enabled in Gmail’s own settings, which is a separate switch.
That the refresh token comes with the client id and secret it was issued against. Without them the grant works until the current access token expires and then stops for good, and that happens long after any warranty window has closed. The test to run is a refresh, not a connection.
Avery Bennett
Social media consultant and growth hacker. Specializes in viral content creation and influencer marketing strategies for brands of all sizes.
