Correos Guide

Correos is Spain's national postal operator. It delivers parcels across Spain, including the Balearic and Canary Islands, Ceuta, and Melilla, to mainland Portugal, and internationally. Delivery is to the door, a Correos office, or a Citypaq locker. Correos Express is a separate carrier and is not covered here.

Sign up for an EasyPost account to obtain a Test and Production API key. See Authentication and Key Management for more information.

Request a Correos shipper account and credentials from Correos. Add the account in the

Carrier Accounts Dashboard or with the API.

The account type is CorreosAccount. Correos provides two key pairs and three account codes:

• CorreosID client ID and client secret (auth_client_id, auth_client_secret)
• API client ID and client secret (api_client_id, api_client_secret), sent on every call
• Contract number (contract_number, maximum 8 characters)
• Client number (client_number, maximum 10 characters)
• Labeller code (labeller_code, maximum 4 characters)

Production and test credentials are separate objects. A credential works only in its own environment. Correos accepts calls only from allowlisted IP addresses, in production and in test.

Use the Carrier Account API to add a Correos account:

curl -X POST https://api.easypost.com/v2/carrier_accounts \
  -u "$EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
  "carrier_account": {
    "type": "CorreosAccount",
    "description": "CorreosAccount",
    "credentials": {
      "api_client_id": "VALUE",
      "api_client_secret": "VALUE",
      "auth_client_id": "VALUE",
      "auth_client_secret": "VALUE",
      "client_number": "VALUE",
      "contract_number": "VALUE",
      "labeller_code": "VALUE"
    },
    "test_credentials": {
      "api_client_id": "VALUE",
      "api_client_secret": "VALUE",
      "auth_client_id": "VALUE",
      "auth_client_secret": "VALUE",
      "client_number": "VALUE",
      "contract_number": "VALUE",
      "labeller_code": "VALUE"
    }
  }
}'

Download an EasyPost Client Library or use the REST API with cURL.

Review the EasyPost Objects documentation to understand requests and responses.

Correos supports rate table rating. Rate tables must be installed for each EasyPost account; otherwise the API returns one-cent placeholder rates (EUR). Contact EasyPost Support for help installing a Correos rate table.

The customer is billed by Correos. Correos uses bill-on-scan.

Correos ships from Spain only. The ship-from country must be Spain, and the ship-from and ship-to addresses need a street and a city.

Domestic services deliver within Spain, including the Balearic and Canary Islands, Ceuta, and Melilla. Shipments crossing into or out of the Canary Islands, Ceuta, or Melilla require a customs declaration. Shipments that stay within the same territory do not. Paq Premium and Paq Estándar also deliver to mainland Portugal, not the Portuguese islands.

International services deliver worldwide outside Spain and require customs data.

Office and Citypaq services need the destination office or locker code. EasyPost does not send that code.

A parcel over the product's weight or size limit is rejected with a 422 before buying and is not rated.

Correos does not provide predefined packages. Use parcel dimensions and weight when creating shipments.

Correos supports buying and one-call buys. The carrier draws PDF and ZPL labels at 4x6. PNG labels are converted from the carrier's ZPL.

A CN22 or CN23 accompanies shipments that cross the EU customs border, including shipments that cross into or out of the Canary Islands, Ceuta, or Melilla. Shipments that stay within the same territory do not. That form is a PDF on A4 paper.

Review the Getting Started Guide for help generating a label.

label_format accepts PDF, ZPL, or PNG.

delivery_confirmation value SIGNATURE is not available for Paq Ligero or Citypaq. DIRECT_SIGNATURE delivers only to the named recipient and requires that recipient's identity document in tax_identifiers.

carrier_insurance_amount is euros only, in whole euros, and is summed across containers into one declared value per shipment. Insurance is not available for Paq Ligero, Paq Azul, or Palet.

On customs shipments, customs_info.contents_type cannot be mixed content. customs_info.non_delivery_option value abandon is international only. endorsement value NO_RETURN_TO_SENDER is international only. incoterm accepts DAP or DDU, and only across a customs border. invoice_number is limited to 15 characters on customs shipments.

tax_identifiers accepts a Spanish DNI, NIE, or CIF, an EU ID, a passport, or the recipient's VAT number for imports. return_address must be the sender's address.

For goods shipments that require a customs declaration, each item needs a description, an HS code (6, 8, or 10 digits), a quantity (maximum 999), a weight, and a value. Item value is euros only. Document shipments do not require item lines. Pass item records under shipment.options.fulfiller_order_items[*].items[*] using description, hs_tariff_number, quantity, item_weight, and item_value.

Manifesting is not supported.

Correos supports voiding through the API. Return labels are not supported.

Limited-quantity and fully regulated hazardous materials are not supported.

Correos supports pickups in Spain only. A pickup is booked for one day and one 3-hour slot: 9–12, 12–15, 15–18, or 18–21 local time. Correos uses the first slot that fits entirely inside the requested window. Pickups are booked 3 to 80 days ahead and carry no charge.

Correos supports tracking through the EasyPost API.

The Carrier Metadata endpoint provides information about Correos service levels, predefined packages, supported features, and shipment options.

Contact Correos for questions about billing, pickups, or carrier requirements. For questions about the EasyPost platform, visit the Help Center.

QR codes, surcharges, and address verification are not supported.

For questions about getting started with the EasyPost API,

talk to a Shipping Expert or contact our Support team.