UTILITY
Read Email Verification Code API
Connect to an IMAP mailbox and extract a verification code from the SUBJECT of a recent email. Polls with retries. Supports Gmail (with App Password), Outlook, and any IMAP server. Generic — works for any platform that puts its code in the subject line; for a token that only appears in the body, use email-read-verification-link.
How to call it
Send one POST to api.upapi.io/email-read-verification-code.post with your key in the X-Api-Key header and the parameters below as a JSON body. Each call spends 1 weighted unit of your monthly quota. The operation times out after 120 seconds. Responses are not cached; every call runs the operation.
POST https://api.upapi.io/email-read-verification-code.post
Read Email Verification Code API reference
Request parameters
- imapHost
- string — IMAP server hostname
- imapPass
- stringrequired — IMAP password or app password
- imapPort
- integer — IMAP server port
- imapUser
- stringrequired — IMAP username (email address)
- maxRetries
- integer — Number of polling attempts
- codePattern
- string — Regex to extract a verification code from the email SUBJECT (the body is not fetched — use email-read-verification-link for body tokens)
- retryDelayMs
- integer — Milliseconds between retry attempts
- senderFilter
- stringrequired — Filter emails by sender (e.g. noreply@redditmail.com)
- maxAgeMinutes
- integer — Only look at emails received within this many minutes
- subjectPattern
- string — Regex pattern to match subject line
- recipientFilter
- string — Filter by recipient address (useful with catch-all domains)
Response fields
- to
- stringrequired — Recipient address
- code
- stringrequired — Extracted verification code
- from
- stringrequired — Sender address
- subject
- stringrequired — Email subject line
- elapsedMs
- integerrequired
- fetchedAt
- stringrequired
- receivedAt
- stringrequired — When the email was received
Example request and response
The example response is generated from this operation’s published output schema — it shows the shape and field names, not values from a recorded call.
{
"imapHost": "imap.gmail.com",
"imapPass": "example",
"imapPort": 993,
"imapUser": "example",
"maxRetries": 5,
"codePattern": "\\b(\\d{6})\\b",
"retryDelayMs": 10000,
"senderFilter": "noreply@redditmail.com",
"maxAgeMinutes": 15
}{
"to": "example",
"code": "US",
"from": "example",
"subject": "example",
"elapsedMs": 1,
"fetchedAt": "example",
"receivedAt": "example"
}Code snippets
cURL
curl -X POST https://api.upapi.io/email-read-verification-code.post \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{ "imapHost": "imap.gmail.com", "imapPass": "example", "imapPort": 993, "imapUser": "example", "maxRetries": 5, "codePattern": "\\b(\\d{6})\\b", "retryDelayMs": 10000, "senderFilter": "noreply@redditmail.com", "maxAgeMinutes": 15 }'JavaScript
const response = await fetch('https://api.upapi.io/email-read-verification-code.post', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY',
},
body: JSON.stringify({
"imapHost": "imap.gmail.com",
"imapPass": "example",
"imapPort": 993,
"imapUser": "example",
"maxRetries": 5,
"codePattern": "\\b(\\d{6})\\b",
"retryDelayMs": 10000,
"senderFilter": "noreply@redditmail.com",
"maxAgeMinutes": 15
}),
});
const data = await response.json();
console.log(data);Python
import requests
response = requests.post(
'https://api.upapi.io/email-read-verification-code.post',
headers={
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY',
},
json={
"imapHost": "imap.gmail.com",
"imapPass": "example",
"imapPort": 993,
"imapUser": "example",
"maxRetries": 5,
"codePattern": "\\b(\\d{6})\\b",
"retryDelayMs": 10000,
"senderFilter": "noreply@redditmail.com",
"maxAgeMinutes": 15
},
)
print(response.json())Go
package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{ "imapHost": "imap.gmail.com", "imapPass": "example", "imapPort": 993, "imapUser": "example", "maxRetries": 5, "codePattern": "\\b(\\d{6})\\b", "retryDelayMs": 10000, "senderFilter": "noreply@redditmail.com", "maxAgeMinutes": 15 }`)
req, _ := http.NewRequest("POST", "https://api.upapi.io/email-read-verification-code.post", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", "YOUR_API_KEY")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]any
json.Unmarshal(body, &result)
fmt.Println(result)
}PHP
<?php
$payload = json_encode([
'imapHost' => 'imap.gmail.com',
'imapPass' => 'example',
'imapPort' => 993,
'imapUser' => 'example',
'maxRetries' => 5,
'codePattern' => '\\b(\\d{6})\\b',
'retryDelayMs' => 10000,
'senderFilter' => 'noreply@redditmail.com',
'maxAgeMinutes' => 15,
]);
$ch = curl_init('https://api.upapi.io/email-read-verification-code.post');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'x-api-key: YOUR_API_KEY',
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
var_dump($data);Ruby
require 'net/http'
require 'uri'
require 'json'
uri = URI('https://api.upapi.io/email-read-verification-code.post')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == 'https'
request = Net::HTTP::Post.new(uri.path)
request['Content-Type'] = 'application/json'
request['x-api-key'] = 'YOUR_API_KEY'
request.body = { "imapHost": "imap.gmail.com", "imapPass": "example", "imapPort": 993, "imapUser": "example", "maxRetries": 5, "codePattern": "\\b(\\d{6})\\b", "retryDelayMs": 10000, "senderFilter": "noreply@redditmail.com", "maxAgeMinutes": 15 }.to_json
response = http.request(request)
puts JSON.parse(response.body)Java
import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
OkHttpClient client = new OkHttpClient();
ObjectMapper mapper = new ObjectMapper();
String json = "{ \"imapHost\": \"imap.gmail.com\", \"imapPass\": \"example\", \"imapPort\": 993, \"imapUser\": \"example\", \"maxRetries\": 5, \"codePattern\": \"\\\\b(\\\\d{6})\\\\b\", \"retryDelayMs\": 10000, \"senderFilter\": \"noreply@redditmail.com\", \"maxAgeMinutes\": 15 }";
RequestBody body = RequestBody.create(json, MediaType.get("application/json"));
Request request = new Request.Builder()
.url("https://api.upapi.io/email-read-verification-code.post")
.post(body)
.addHeader("Content-Type", "application/json")
.addHeader("x-api-key", "YOUR_API_KEY")
.build();
try (Response response = client.newCall(request).execute()) {
Map<?, ?> result = mapper.readValue(response.body().string(), Map.class);
System.out.println(result);
}C#
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var payload = JsonSerializer.Deserialize<object>("{ \"imapHost\": \"imap.gmail.com\", \"imapPass\": \"example\", \"imapPort\": 993, \"imapUser\": \"example\", \"maxRetries\": 5, \"codePattern\": \"\\\\b(\\\\d{6})\\\\b\", \"retryDelayMs\": 10000, \"senderFilter\": \"noreply@redditmail.com\", \"maxAgeMinutes\": 15 }");
var response = await client.PostAsJsonAsync("https://api.upapi.io/email-read-verification-code.post", payload);
var result = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(result);Frequently asked questions
How much does the Read Email Verification Code API cost per call?
Each call spends 1 weighted unit of your plan's monthly quota. Full pricing is at https://upapi.io/pricing.
How do I authenticate to the Read Email Verification Code API?
Send your key in the X-Api-Key header. A free guest key is available without creating an account.
Are Read Email Verification Code API responses cached?
No — every call runs the operation live; responses are not cached.