xref: /curl/docs/cmdline-opts/header.md (revision 1f1975b8)
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Long: header
5Short: H
6Arg: <header/@file>
7Help: Pass custom header(s) to server
8Protocols: HTTP IMAP SMTP
9Category: http imap smtp
10Added: 5.0
11Multi: append
12See-also:
13  - user-agent
14  - referer
15Example:
16  - -H "X-First-Name: Joe" $URL
17  - -H "User-Agent: yes-please/2000" $URL
18  - -H "Host:" $URL
19  - -H @headers.txt $URL
20---
21
22# `--header`
23
24Extra header to include in information sent. When used within an HTTP request,
25it is added to the regular request headers.
26
27For an IMAP or SMTP MIME uploaded mail built with --form options, it is
28prepended to the resulting MIME document, effectively including it at the mail
29global level. It does not affect raw uploaded mails (Added in 7.56.0).
30
31You may specify any number of extra headers. Note that if you should add a
32custom header that has the same name as one of the internal ones curl would
33use, your externally set header is used instead of the internal one. This
34allows you to make even trickier stuff than curl would normally do. You should
35not replace internally set headers without knowing perfectly well what you are
36doing. Remove an internal header by giving a replacement without content on
37the right side of the colon, as in: -H `Host:`. If you send the custom header
38with no-value then its header must be terminated with a semicolon, such as -H
39`X-Custom-Header;` to send `X-Custom-Header:`.
40
41curl makes sure that each header you add/replace is sent with the proper
42end-of-line marker, you should thus **not** add that as a part of the header
43content: do not add newlines or carriage returns, they only mess things up for
44you. curl passes on the verbatim string you give it without any filter or
45other safe guards. That includes white space and control characters.
46
47This option can take an argument in @filename style, which then adds a header
48for each line in the input file. Using @- makes curl read the header file from
49stdin. (Added in 7.55.0)
50
51Please note that most anti-spam utilities check the presence and value of
52several MIME mail headers: these are `From:`, `To:`, `Date:` and `Subject:`
53among others and should be added with this option.
54
55You need --proxy-header to send custom headers intended for an HTTP proxy.
56(Added in 7.37.0)
57
58Passing on a "Transfer-Encoding: chunked" header when doing an HTTP request
59with a request body, makes curl send the data using chunked encoding.
60
61**WARNING**: headers set with this option are set in all HTTP requests - even
62after redirects are followed, like when told with --location. This can lead to
63the header being sent to other hosts than the original host, so sensitive
64headers should be used with caution combined with following redirects.
65